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.

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?

share|improve this question

migrated from stackoverflow.com Aug 30 '11 at 20:56

This question came from our site for professional and enthusiast programmers.

4  
FWIW I think that technical writing is part of software development (and therefore 'programming-related'), just as much as other tasks like 'requirements gathering', and 'testing', and so on. –  ChrisW May 12 '09 at 17:45
show 1 more comment

18 Answers

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

share|improve this answer
1  
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 May 12 '09 at 17:42
show 3 more comments

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

The essential reference for technical writers, editors, journalists, and everyone else who writes about computer technology.

Developed by Microsoft’s senior editors and content managers, this manual of style captures the up-to-date standards and best practices for delivering clear and consistent technical communications... Whether you’re creating print documentation, online help, Web content, or other communications, you’ll get the information and examples you need to maximize the impact and precision of your message.

Get clear, concise guidance to help you:

  • Use technical terms correctly and consistently—including do’s, don’ts, and alternatives for usage.
  • Employ the appropriate tone and voice for your audience.
  • Produce written and visual content suitable for a worldwide audience.
  • Apply best practices for writing and tagging Web content.
  • Write better documentation—from dialog boxes and error messages to Web pages and software code.
  • Know the standards for creating accessible communications.
  • Optimize your indexes, cross-references, and keyword lists.
  • Get fast answers on spelling, grammar, and punctuation...
share|improve this answer
add comment

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.

share|improve this answer
show 1 more comment

Avoid using a passive voice.

share|improve this answer
1  
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 May 12 '09 at 18:01
1  
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 Mar 4 '10 at 13:00
show 2 more comments

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

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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

share|improve this answer
add comment

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

share|improve this answer
add comment

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.

share|improve this answer
show 4 more comments

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

share|improve this answer
add comment

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.

share|improve this answer
show 2 more comments

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!

share|improve this answer
add comment

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

share|improve this answer
show 1 more comment

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

share|improve this answer
add comment

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.

share|improve this answer
add comment

I'm surprised nobody has mentioned this: read a lot of documentation. Specifically, read documentation in a similar format to that you will be writing. Read for information you need. Learn to distinguish between documentation you find useful and documentation you don't.

Doing so will not only help put yourself in the place of the reader, but will help your brain absorb the style of writing you need to do.

share|improve this answer
1  
+1 I was surprised at this too. I have some old copies of the Bell Labs Technical Journal and the IBM Systems Journal that I re-read periodically (sorry). For user manuals, see if you can get some old IBM mainframe manuals. The IBM doc team in Poughkeepsie was top-notch, you can learn a lot about good document structure and page layout. Technical books by Bell Labs staff tend to be good too; K&R's The C Programming Language, Kernighan and Plaugher's The Practice of Programming, Jon Bentley's Programming Pearls are all information-dense but highly readable. –  TMN Nov 1 '11 at 14:37
add comment

Technical writing can be tricky, I've realized, as the writer is supposed to know what aspects of an esoteric subject matter to decipher. The complexity derived from that is usually from the writer's personal understanding of the topic; it's hard to raise the abstraction. That said, I recommend doing the following religiously:

  • Outline. Outline. Outline! This is the most important act should feel poised to carry out. Think of it as a map. As a technical writer, you're scaling gnarly terrain, surveying it to help out a crowd of curious, distant observers. An outline will guide you as well as push you to explore intricacies (which is what your observers may want); you'll cover most ground this way. Plus, it helps keeping your execution organized.
  • Recognize that, as the writer, you're the superior. This may seem like a good way to feel full of yourself -- in essence, I'm encouraging that. The reason is that if you think you're superior to someone else, you'll feel confident about what you're explaining. As a consequence, you'll feel ready to elaborate. Arrogance should not be dismissed, as long as you avoid showing it in your writing. That brings me to my next tip, actually:
  • Remain as objective as possible. I deal with many students who have trouble differentiating between personal writing and impersonal writing. Although I don't encourage you to write to bore, I don't recommend you fall into the trap of thinking that you should write something terribly 'human.' (I shouldn't feel like you're my friend when I'm done reading.) And aside from the objective tone, you should make sure you avoid explaining personal-sounding examples: e.g. If you're explaining mathematical lemma in a paper on combinatorics, try to avoid writing about the frequency of your cat's fur-licking to explain something like the application of Schubert polynomials. Stick to the math; stick within the domain of your paper to avoid ambiguity.
  • "What if" is the start of beautiful work, but it's also potentially harmful. By this, I simply mean that while asking questions that force you to peruse the inner-workings of the topic you're trying to explain, it can also cause you to create something so dense that it confuses the heck out of you and your future readers. Brevity is beautiful, elaboration is too, but knowing when there's too much is more favorable than one or the other.
  • Read pieces of work that were written technically. By doing this, you should pick up the gist of what you should have by the end of your stint as a technical writer. If you're writing something programming-related, read through lots of online documentation. If you're writing about something in the natural sciences, read through some research publications. Google Scholar is your friend.
  • Emphasis and punctuation. Although you may have an editor by your side, waiting to touch-up your work, make sure you meticulously unravel everything with a fine-tooth comb. Commas, periods, question marks, etc... are important in writing something that assists the reader in organizing the information in their brain; bold-facing and italicizing is just as important, if not more important than the aforementioned. Bolding and italicizing key words and phrases can be pivotal is writing something understandable and useful.
  • Realize that your writing may be used as a desktop reference. That's why typographic emphasis, sentence structure, and the organization of your writing are important.

I've written a significant number of pieces for students and professionals over the years, and although I'm not the best writer, I've received some nice feedback because I kept the above in mind. I'm not a professional at this point, but I can almost guarantee that if you follow at least half of what I suggested, your technical writing will be better than what it may be currently.

Good luck! I hope this helped!

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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