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.
After listening to hundreds of podcast interviews over the years I finally got to be the subject of one myself. Nikhil Krishna interviewed me for the Software Engineering Radio podcast, which is sponsored by the IEEE.
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…
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…
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…
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…
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…
