Category: Writing
-
Englishes
American Tech English, is, I think, a kind of constructed English, similar to Simplified English. It’s not quite as rigorously enforced as Simplified English, but I am one of its enforcers. I will strip nuance out of sentences, and prioritize simple grammatical structure over fluidity, pacing, or rhythm. If a sentence could possibly be two…
-
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…
-
It’s December Eve, are you ready?
You are probably familiar with the retail rhythms of the seasons. You can think of it as what kind of candy you can buy, when chocolate moves smoothly from ghosts to pumpkins to tree decorations to hearts. If you work in any kind of e-commerce, from November to mid-January is a code-freeze all-hands-on-deck experience. Software…
-
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!…
-
Semantic meaning is everywhere
Semantic labeling could make our world better, if we valued it. Even our conference slides.
-
From the editorial scrap heap
In 2020, we got some excellent examples of how different approaches to planning, capacity management, and emergency response can make a real difference between a public-health problem and a slow-motion mass-casualty event.
-
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…
-
What is a documentation architect?
When I was at Write the Docs 2015, several people asked me about the title I have in my LinkedIn heading: Documentation Architect. What did I mean by that? How is it different than content management or development architecture? What a documentation architect isn’t A documentation architect isn’t psychic. They can’t figure out your business…
-
The New Sheriff in Town: Bringing Documentation Out of Chaos (Write the Docs, 2014)
By the time we get to mid-career, most of us have specialized, by technology, or organization type, or document type. We have a comfort zone. I have specialized in walking into chaos and creating order. I’ve done it enough times that I have a sequence of steps I follow. I imagine myself as a sheriff walking…