documenting software

I’ve done some copyediting as part of my job, especially with marketing material. Certain basic mistakes come up so often that I made a list that I’ve been tempted to give to whoever gave me the original content and say “please make sure that it doesn’t have any of these problems first!” I didn’t, but for those who are interested, following these simple rules will make your writing look more professional. The nice thing about these is that, unlike with truly good writing, no skill and very…

Writing about software: lists

Bulleted lists Numbered lists Other kinds of lists

As part of my sporadic series on documenting software, I wanted to devote a posting to lists, because they play a much larger role in tech writing than they do in typical prose. People reading a chapter of software documentation are less likely to read it from beginning to end than they are to skim it looking for an answer, and if the question is “how do I accomplish task X”, the answer is probably a multi-part answer. When the instructions for task X are broken up into separate list…

Writing about software: bad words

Featuring the "f" word.

As the third part of my series on writing about software, I’m writing about overly used words to avoid because they’re nearly meaningless. For a start, read George Orwell’s essay Politics and the English Language. The problem he speaks of, in which people use bigger words than they need to because they think that it makes them sound well-informed and important, is particularly endemic to the tech world, and especially acute among the marketing and sales people in all but the…

Writing about software: what documentation does a product need?

Helping users get the most value from a piece of software.

Based on my experience as a tech writer and a few books I’ve written since then, someone recently asked me for advice on documenting a complex software product, and I thought I’d share my advice here. After writing it I remembered that two years ago I submitted a proposal to O’Reilly for a book on writing about software. After kicking the idea around with Simon St. Laurent a bit, I decided not to go through with it. One thing that put me off was his warning that a place like…