Tag: technical writing
-
Linters and style guides and standards and tests
Consistency matters. Consistency matters for branding, because of copyright and recognition reasons, because you’re investing lots of money into that exact arrangement of letters. Consistency matters for code, because computers are terrible at approximation and “close enough”. Consistency matters for documentation, because human language is really hard and weird. Consistency matters, but it’s wicked hard to…
-
When you stare into the blank page, it stares back at you
I didn’t write The Great American Novel during the pandemic. I’m good with that. Instead, I worked with an amazing team to write the best book we could on how to do technical writing when you are not a technical writer. I finally believe this book is really real, because look, there are pre-order buttons!…
-
Sharpen the axe with personas
I haven’t been writing much about writing lately, because I have a big! new! exciting! project coming up. I’ll tell you more about that later. However, this weekend I ended up in a twitter conversation about how I get myself unstuck when a piece of writing isn’t working, and I thought I’d share. Abraham Lincoln…
-
Documentation for DevOps: A DevOpsDays Open Space Writeup
I’m borrowing this image from my friends at Chef, because it’s really funny to pretend that it’s possible to just sprinkle on “devops”, something that is about cultural change at every level. At every DevOpsDays I go to (and that’s quite a few), I propose/wrangle/run two open spaces. One is about feature flags/canary launches/hypothesis-driven development,…
-
Retrograde tooling
We’ve reached a tipping point in technical writing, and we need to deal with it. The future is not going to involve producing documents, it’s going to be producing seamlessly integrated content in and around products, and that means we need to change our expectations around tooling. This is going to hurt, but hopefully in…
-
Why on earth would developers WANT to write documentation?
This week I was at DevOpsDays Minneapolis, which was an amazing, warm, and inclusive event. There were at least three open spaces on documentation, communication, and related problems, and I didn’t propose any of them! The question the devops world keeps asking, over and over again is, How do I get developers to write anything?…
-
New job title: Developer Advocate
I’ve had a lot of job titles in my career: Technical Writing Intern Queen of Documentation (It was 2000, OK?) Technical Writer I, II, III Technical Communicator Senior Technical Writer Technical Writing Consultant Documentation Architect Documentation Mercenary You might notice a theme there. I’ve been a technical writer for a lot of different companies, because…
-
Software and pink collars
Yesterday, I said this: The real reasons we don't have docs/ux/pm bootcamps/code schools/hack days: 1) They're coded as feminine2) They pay less Code patriarchy. — Heidi, Sticker Thoughtleader (@wiredferret) July 4, 2017 And I want to come back and address it in a bit more depth, because someone called it “a bold statement”, and it…
-
The Cardinal Virtues? of Technical Writing
First, a disclaimer: Medium served me this article, but it’s a year old. Weird. Nonetheless, I have things to say about the content. The Virtues of Technical Writing, by a pseudonymous writer Introduction They are gleaned from a Bachelor of Science degree in Scientific and Technical Communication from the University of Minnesota’s Writing Studies Department,…