documenting software

More advice about software documentation

Especially documenting APIs.

Early last year, in the blog entry Doing a podcast interview about technical writing, I described an interview I did for the IEEE Software Engineering Radio podcast. Listening to it again this week I saw that I covered a lot of good ground. Since then I have thought of a few other points I wish I’d mentioned, so here they are in another bulleted list. Because of some recent experience I had enough thoughts about documenting APIs that I gave that discussion its own section below.

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…

So You Want to Write a Book (about software)?

Advice from some people who know.

This installment of my series on writing about software is brief: O’Reilly has an excellent online publication called So You Want to Write a Book?, and it’s full of good advice whether you plan to write a complete book or not. O’Reilly isn’t the only publisher of computer books out there, but they’re certainly one of the key ones, and this book offers excellent advice for preparing your content and for assembling all the necessary information if you want to move…

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…