views:

662

answers:

15

Writing documentation is part of programming, and writing well is part of what makes the documentation useful.

So, what are some hints or guidelines for good writing in the technical realm? What are some resources (on-line or on dead trees) which might help me to improve my documentation?

+5  A: 

Points to keep in mind when doing technical writing:

  • Know your audience Know what they expect from this document, know how much background you can be sure they have. If your audience may span a wide range of abilities, add a glossary and/or appendixes to help bring the least able up to speed.

  • Know the subject. You must have a mastery of the topic beyond what you expect to teach.

  • Spelling and grammar. Know it, love it, do it. Or at lease use the tools available to help you.

  • Introduce possibly unfamiliar jargon and symbols before using it.

  • Keep it as simple as possible. Short, declarative sentence are preferred where possible.

  • Figures, tables, and sample code.

  • Good formatting.

  • Good use of white space.

To emphasize the first two points:

The first two questions when writing are always: "What is this about?" and "Who is it for?"

dmckee
Technical writing is purposeful: the questions to ask are, "Why is the intending audience reading this? What task are they trying to do, which reading this is supposed to help them with?"
ChrisW
Not programming related - all the above apply to ANY kind of technical writing.
anon
if we are talking about "technical writing", it is important that words are spelled correctly. It would be "Know your audience.". Not "you audience".
Devtron
@Devtron: ::blushes::
dmckee
+2  A: 

Microsoft has a Manual of Style for tech writing. That would be a good start.

Jon B
+7  A: 

Practice. Simply writing and reading what you've written will make you a better writer. Start a blog and get some practice by writing articles on technical topics you're passionate about.

** The added bonus is all the stuff you'll learn while researching your posts.

Vinnie
+1  A: 

Avoid using a passive voice.

Shane C. Mason
It is true that overuse of the passive voice can make writing feel leaden. However, I find that over-emphasis of this advice leads to unnatural contortions in an effort to force an active verb into places where "to be" belongs. Keep this in mind, but use your head about it...
dmckee
I was contemplating downvoting this because I think there's nothing wrong with the passive voice necessarily - there are many cases where it's perfectly appropriate, and just saying "avoid using a passive voice" as a blanket admonishment leads to exactly the kind of problems dmckee is talking about. But in practice I notice that many technical writers (I'm thinking of scientists but this could apply to programmers as well) do overuse the passive voice and sometimes even actively discourage active voice. So maybe they do need to make a more conscious effort to avoid passive statements.
David Zaslavsky
What both of you say is absolutely true - sometimes a sentence is better understood in a passive voice (see what I did there :). Practicality over purity, right? In almost all cases, the passive voice should be avoided for the sake of readability, clarity and to keep the readers interest.
Shane C. Mason
The injunction against the passive voice is made because all kinds of leaden, lacklustre prose makes excessive use of it. However, this makes passive voice a proxy for problems in writing - it is not a problem in itself, is itself used in good writing, and the attempt to improve writing by eliminating the proxy typically results in even worse writing. Plus, relatively few people seem to be able to reliably identify the passive voice, rendering the application of the advice often absurd.
Charles Stewart
+1  A: 

If you're looking for more formal training, many community colleges offer technical writing classes.

KevMo
+2  A: 

Practice, practice, practice. The more you write, the more you'll develop your own personal style. I know you asked about tech writing, and you'll get a lot of references to style guides and the like, but the writing part is at least as important. Also, solicit feedback on the writing that you already do.

Mark Bessey
+5  A: 

Just like code reviews are crucial for improving coding ability, getting feedback is crucial to improving your writing. Solicit feedback from people whose writing you admire. Never be defensive about the criticism you receive. Find people who can give you very specific feedback on what is good, and what is not good, about your writing.

Robert
+1  A: 

I recommend reading "Mathematical Writing" by Donald Knuth. Although the primary audience are scientists, especially mathematicians, most is applicable to general technical writing, too.

Meinersbur
+2  A: 

Practice.

Be concise, use small words, don't use jargon.

Be aware of the topic, the audience, and what the audience wants to do with the topic.

And here are a few books:

Handbook of Technical Writing - http://www.amazon.com/Handbook-Technical-Writing-Gerald-Alred/dp/0312477074/ref=ed_oe_o

Style (Williams) - http://www.amazon.com/Style-Lessons-Clarity-Grace-9th/dp/0321479351/ref=sr_1_1?ie=UTF8&s=books&qid=1242150834&sr=1-1

+2  A: 

Put yourself in the place of your reader, their technical level, their needs. All too often we know the subject too well. We assume knowledge about things that the reader will not have.

Yesterday I was trying to use an application. I could not find the screen for setting a certain parameter. I went through the documentation which did a great job of explaining the various settings, what they did, and how to use them. Nowhere did it show how to bring up that screen. I spent almost an hour before I finally found out which obscure button click brought up this screen.

The person writing the documentation assumed I would know how to access it.

Jim C
I like information in a manual to have a regular structure. To take this as an example, once you discover that you need to say how to bring up the screen in the first place, then not only insert that information into this section but also add similar information into other similar sections.
ChrisW
@ChrisW I disagree. Just refer back to it. "1. Open the preferences dialog (see page 3)."
Adam Jaskiewicz
Adam, what I meant was that once you realize that you need to tell people how to open the Preferences dialog, then also add similar (not identical) information to related sections: i.e. how to open Properties dialog, the Options dialog, the Tools dialog, etc.
ChrisW
Oh, OK. I thought you were suggesting duplicating the "How to open the prefs dialog" directions everywhere you need to open it.
Adam Jaskiewicz
+2  A: 

By the way, if you haven't already, please learn proper grammar and spelling. It's horrible what technical people do to the language.

Brian
+2  A: 

Keep a programmers/developers journal and try to write something in it every day. A technical blog works as well. The important thing is to write about the technical decisions you make like:

  • Why you designed a class in a particular way
  • The implications of an architecture decision
  • The development process for a particular algorithm or method of which you are proud.

There are many other things you could write about, but focus on the technical and try to make it easy to understand.

When you feel comfortable writing for yourself, you can publish your journal as a blog, and look for feedback.

Just like coders learn to write better code by programming at the edge of their ability/comfort, writers learn to write better by writing at the edge of their ability.

The style guide suggestions by other posters are good, but the best in my opinion remains Strunk & White, The Elements of Style. They even have a badge named after it here on SO.

Gary.Ray
+2  A: 

Find a person in your team who you reckon is good at it. Then, send him/her all documents you write for a review. You'll be surprised by how many things you can learn from him/her!

ya23
+2  A: 

We do peer review of all technical documents (functional specs, design docs, etc...) that almost always turn up something that I missed or should have done differently or could have explained better.

After each review meeting I do a personal lessons learned exercise in my journal (whether I wrote the reviewed document or not). I then take the results of these lessons learned exercises and add them to check-lists that I use when composing my technical docs.

I've just started this, but you can check out the results so far on my web site (via my profile).

Robert Gowland
+1: Authors nearly always miss certain kinds of problems in their own writing.
Charles Stewart
+1  A: 

One way to improve technical writing skills is to edit questions and answers here on Stack Overflow.

There is plenty to correct and to improve...

Peter Mortensen