Archive for Tech Writing

On the uses of encyclopedias

I’ve finally finished reading Andrew Brown’s A Brief History of Encyclopaedias. I continued to find it both interesting and annoying all the way through. (It’s less than 120 pages long, but it took me a few days to read it because I kept falling asleep. That’s not the book’s fault; I was inexplicably sleepy all […]

Presenting in absentia

For our annual tech writer conference at work, I gave a talk about the sixteen-year history of our developer docs style guide; I created the original version of the guide in 2005. The conference had the presenters prerecord their talks this year, so I recorded mine before I went on leave. The people running the […]

Tech writer interviewing: basic algorithms

When you’re interviewing for a developer-docs-oriented tech-writing job in the software industry, chances are fairly good that at some point in the process, you’ll be asked to read some code and explain what it does. So before you apply, I strongly recommend familiarizing yourself with some common simple things that a brief code sample might […]

What is the subject of this document?

Probably the most common problem that I see in technical documentation is a failure to say upfront what the thing is that you’re documenting. I feel that in most cases, one of the first pages of the documentation set should have a sentence early on in the page that says something like “[Product name] is […]