Document Everything - It Helps!

Strong documentation is the product of good writing. It's funny I suggest that because for the longest time, my idea of writing well applied only to writing lines of code. But when I started my internship at Acquia, I quickly realized the importance of writing everything well. Every project here depends on easy-to-understand, descriptive writing.

I immediately took more notes, scribbling down anything and everything. When introduced to new tools, technologies and services, I look up unfamiliar terms on Google to find helpful blog posts, articles and API documentation to improve my understanding. During one of these searches I thought of an apt Chinese proverb, The palest ink is better than the best memory.

For some reason, documentation doesn't interest many people, but it's important. Consider this case study: Programmers from different cultures contribute to the same project. Although a diverse group will produce many fantastic ideas, sometimes it's difficult figuring out the various idioms and writing styles used by the many contributors. That's because more often than not, little thought is given to proper documentation. As a result, a hodge-podge record that's left behind will make an inspired project look uninspired and frustrate others.

It's important to treat all documentation like the instructions manual of a child's Christmas toy. Without instructions, a toy manufacturer will probably hear about an unhappy child from a dissatisfied adult consumer. Next time that you debate whether or not to fully document a project, remember the great value the details will have to your customer.

Here are some benefits of documentation:

• A complete written document clarifies your thoughts and better explains the product. This ultimately increases efficiency.
• It makes things more real.
• A strong document increases consumer trust and creates stability.
• You never know when someone will need it: A document is always, always useful for reference.

Recently, I was asked to write a document for an Acquia project. I did some digging and found that Markdown (a text formatting syntax inspired by plain text) is a good tool for styling text on the Web. Markdown's features are so attractive that I now use it to not only write documents but also my blog posts.

You may choose another way to document, but no matter what, don't forget to consider the following details when creating technical product documentation:

• Product introduction, key concepts and features
• Sub-products or modules description
• Application installation or configuration process
• License Information (if needed)
• Authors
• Troubleshooting
• FAQs
• Contact information (email, phone, website, etc.)

Things don't always work right the first time, so instead of going back step-by-step and messing with everything, documentation will reference what you did along the way and hopefully pinpoint the problem.

I'd love to hear from you. How important is documentation to you, and what tools and processes do you use when documenting project work? Please let me know in the comments section below.