Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

This question already has an answer here:

As a programmer, technical writing is an important skill to me. I get a lot of fun from it. I also learned from some good technical articles and books. What I need are technical writing principles or rules to refresh my mind.

Any relevant article, tutorial, and presentation are welcome, and your own experience will also be great!

share|improve this question

marked as duplicate by gnat, BЈовић, Kilian Foth, Jalayn, GlenH7 Jun 20 '13 at 12:54

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

add comment

8 Answers

up vote 9 down vote accepted

The first rule of writing:

  • Writing is more about re-writing than it is about putting your thoughts on paper. (from an editor I worked with)

The second is related:

  • Always have your writing reviewed by someone else. They will be able to catch logic errors, grammar mistakes, and even if the content doesn't work for the target audience.

Probably the most difficult part that I've found with technical writing is figuring out what not to include. You need to bring your listeners up to your point of understanding what you do, but it is so easy to get bogged down in details that aren't important. If your reviewer is lost, they will start to ask you many pointed questions. They are really good for helping you determine what's important and what isn't.

share|improve this answer
    
Thanks! Could you explain the 'first rule'? Sorry for my coarse English. –  卢声远 Shengyuan Lu Feb 1 '11 at 13:36
2  
Sure. When you first put your thoughts on paper they are very coarse, and unpolished. You haven't found your "voice" yet (the style of writing). When you go back and read what you wrote, inevitably you'll hate it. That happens to me all the time. Then you go back and rewrite it, fixing everything you felt was wrong, or trying to explain things a different way. In my attempt to writ a book (still not complete), I ended up rewriting the first chapter 3 times before I moved on. By the time I got through the second chapter things got easier. –  Berin Loritsch Feb 1 '11 at 13:46
add comment

This is one of best advices I've come across:

State your message in one sentence. That is your title. Write one paragraph justifying the message. That is your abstract. Circle each phrase in the abstract that needs clarification or more context. Write a paragraph or two for each such phrase. That is the body of your report. Identify each sentence in the body that needs clarification and write a paragraph or two in the appendix. Include your contact information for readers who require further detail.

— William A. Wood, September 8, 2005 (source)

share|improve this answer
add comment

Write in simple short sentences.

Don't assume anything, explain everything. You readers might not know what TDD is test driven development. Spell it out the first time you use it.

Edit your writing. After writing, set it aside for several hours, or days, then read it. You will find many errors and mistakes. Fix them. Now get some one else to read it, they will find more.

Use graphics. A picture is worth a thousand words or more. Screen captures can be pasted into just about any document.

Go step by step. When preforming a task, list every single step. Don't just say "open the file", break it down, "open a file by clicking on FILE in the menu and then clicking on OPEN". Experienced readers will skip over details they know, but with inexperienced readers be detailed.

share|improve this answer
add comment

'Consider your audience' is the main one. You don't want to talk about bit flipping when writing for managers, or explain basics to the resident ubergeek. Neither one of them will get anything out of it, and they'll both think you're wasting their time.

share|improve this answer
add comment

First learn to write clearly and concisely. In order of importance, technical writing should be:

  1. Accurate
  2. Complete
  3. Appropriate

If you screw up #1, you lose your audience.

You also need to do an audience analysis. Writing for a seasoned developer is much different that for a beginning developer.

Technical documents are typically written in the reverse order in which users read them. First you write the reference section, then any guide/how-to, and finally a tutorial.

If at all possible, find a good editor to look over your work. They'll concentrate on the writing part.

Don't be afraid to use a conversational tone. Read your passages aloud. You will often discover stilted or obtuse phrases that need to be revised. Use the active voice. That means avoiding statements like "After the file is loaded, ..." I personally dislike the future tense I often see in technical docs, like "This method will ...". Will when? Sometime before the sun implodes into a red star?

You might consider a night/weekend class at a local community college. As I used to say when I was documenting the Unix Programmer's Manual, the first 10 years are the hardest, LOL.

share|improve this answer
add comment

Iteration works in writing technical document also as it works in Software Development. Make sure you polish your technical document by iterating multiple times on the initial draft.

share|improve this answer
add comment

There's lot of good advice here. To throw in another tidbit, when I was working at IBM as a technical writer on VisualAge for Java (I was doing as much development as writing at the time, and moved back into full time development after that), we categorized information into three basic groups:

  • Conceptual,
  • Task, and
  • Reference

This really applies when you have larger chunks of documentation to work on, like a book or online help for an application. Often you want to be able to refer to concepts via links in tasks, and also to detailed reference information, but you don't want to bog down the reader with these details. Often when people are interested in "just doing it" they want the steps laid out for them and that's all. Other people like to have a background on what they are working with before trying something specific. And yet others want to know an excruciating level of detail, and they will dig into the reference docs.

share|improve this answer
add comment

First rule of technical writing:

Do not use the word utilize! In other words, smaller words are better if they have the same meaning.

My pet peeve now being out of the way, I can answer more fully. Technical writing is all about the audience not the writer. Do everything you can to make the text work for the audience. This includes:

  • Use graphs and pictures.
  • Define all acronyms and technical terms in an appendix. Write out the meaning of every acronym the first time you use it. Example: "In Test-Driven Development (TDD), ..."
  • Have a short summary at the beginning.
  • Use lots of white space. (Paragraphs that are a-page-and-half long are difficult to understand and most people won't bother!)
  • Think of the reader's viewpoint not yours. What does he or she need to get out of the document.
  • Spelling, grammar, punctuation, etc. count. Do not write as if you are texting someone!
share|improve this answer
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.