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?

8

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?"

7

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.

5

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.

2

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

2

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.

2

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

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.

2

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

2

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.

2

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!

2

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).

1

Avoid using a passive voice.

1

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

1

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

1

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...

0

In school and university, we learn that it is essential to write long documents. Therefore, a lot of people learn to fill a lot of stuff between the lines to create pages. In addition to this, they never see a problem when somebody tries to explain something with 20 sentences that could have been said in one or two

One of the most difficult to be short and precise instead of long and loose.