How can the process of creating and maintaining documentation be improved?

Question

I know it's a very subjective question , but this is one section of Software Engineering wherein I haven't seen any improvement in terms of how we can do it in a better way. I guess every programmer does documentation with some frustration, but when working I feel it's the most important tool for me. How can the process of creating and maintaining documentation be done in a better way?

Answer 1

There is no silver bullet. Like other aspects of programming, you need to decompose the problem and tackle one area at a time.

Here are some ideas that can (in my experience) be helpful:

Reduce the need for documentation

• There are often better ways to communicate than through documents, eg. face-to-face
• Identify which documents have little value and stop producing them
• Well structured programs need less documentation
• Use meaningful variable names etc to reduce the need to document
• Use code comments wisely
• Link to appropriate web articles rather than reproducing them in your documentation

Generate documentation

• Class diagrams can often be generated from code and then annotated
• E-R diagrams can be often be generated from a databases
• Use tools like javadoc to document APIs

Choose the right tools

• If you want documentation to be developed collaboratively, use something like a Wiki.
• If you want documentation to be kept in step with source code, keep the documentation in source control.
• Consider the benefits of an integrated bug-tracking / knowledge-base / source control solution
• Pictures can speak a thousand words. Use diagramming tools etc.
• Use an interactive whiteboard in meetings and keep a copy of things written on the board (or if using a regular whiteboard, take a photo).

Choose the right medium

• Instead of writing everything down, consider using video or audio recordings (great for both requirements capture and end-user documents) and photographs.
• Archive emails about the project

Choose the right quality

• Not all documents have to be polished. Sometimes, a rough sketch is enough as long as everyone can find it when it is needed.

Choose the right people

People should document according to the domain of their expertise. For example, users should write user documentation (after all, users best understand the business problems that the software solves, and will express their understanding of the software in business terms).

Build the right culture

Sometimes, documentation problems are really people problems:

• If you feel that documentation is the best way to preserve knowledge in your company, the real issue may be one of staff retention.
• If you feel the need to document every detail of who did what, the real issue may be that your organisation fosters a blame culture.
• If you feel the need to document as a means to share knowledge, you may benefit from finding out why people don't just talk to each other.
• If you're documenting every detail of every little decision, you may find find that you're working in a low trust environment.