Archive for Tech Writing
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 […]
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 […]
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 […]
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 […]
I've seen several potentially misleading graphs in articles lately, so here's a reminder of a couple of common y-axis issues:...
For those unfamiliar with it: Markdown is “a text-to-HTML conversion tool”—or, to put it another way, a simplified way to...
Note to people applying for jobs: It's probably not a good idea to say, in your cover letter or resume,...
I've interviewed a lot of tech writer candidates in my past few jobs, and it occurs to me that it...