Some software development groups must document everything. This often results from legal, regulatory or compliance demands. Although, it can also be a cultural phenomenon — some managers simply won’t accept anything unless it’s in writing.
Do everything you can to minimize the volume of written exchanges. Information overload is not just a cute phrase. It’s real and it causes lots of confusion and errors.
Some reasons why you might need a (virtual) paper trail
Written artifacts are often used as a vehicle to get people to think. They also serve as verification that the thinking happened. The artifact itself isn’t what’s important. It’s the effect that it has on people that matters. The challenge lies in getting people to actually read the artifact.
Other written artifacts suggest or even enforce a process. For example, action “A” takes place and is documented. The document triggers action “B” (this scenario may be repeated multiple times during a project). This approach is particularly useful when different groups or even companies are involved in a collective effort.
Finally, written artifacts may serve as a historical roadmap depicting how the software evolved and describing the current implementation. As above, this can be particularly useful when multiple groups are involved.
Keeping the project artifacts from becoming a burden gives you a better chance of getting people to write them. Keeping the documents lean and agile gives you a better chance of getting people to read them.
If your team is spending significant time merely documenting as opposed to solving and delivering, you have a problem. I’ve observed many a developer spend vast amounts of time on document layout, formatting and pretty-printing. It doesn’t impress me and it won’t help your team deliver better software.
If you’re forced to produce large quantities of written artifacts, follow these tips for minimizing the burden.
Ten Tips for Writing Better Documents
- Focus on content not art. If fancy artifacts are required, use a simple, clean template. Be sure that the content captures the reader’s attention not the fancy fonts and artwork.
- Adopt the attitude that less is more. Deliver brief and direct documentation resisting the urge to write a novel. More of what you write will actually be read.
- Don’t duplicate content. Never copy and paste lengthy sections from one document to another. Always reference the source.
- Keep it informal. You may need some formal documentation but don’t write everything in a formal way. Make it informal unless formality is required. Often, a simple photo of a whiteboard is good enough. Why turn it into a fancy computer diagram?
- Avoid long, unstructured documents. Group related material into clearly defined sections.
- Use simple sentence structures avoiding long, compound sentences that are hard to follow. Also keep paragraphs short as whitespace improves readability.
- Use bullet points to slow the reader down and draw attention to important ideas that don’t need to be understood in a particular order.
- Use numbered lists to draw attention to information that should be read in the order presented.
- Include graphs, charts and photos for improved understanding but don’t go overboard.
- Take advantage of bolding, colored text and links to highlight words and draw attention to them.
Documentation is important. Formality and bulk are not. Keep it lean and agile.