Mfon."A bug in the code is worth two in the documentation." - Unknown
My technical mentors always emphasize the need to document code. I admit it is quite tasking. Hence, many programmers do not document code. Understandably, they prefer to spend more time writing code.
Joe Armstrong - the computer scientist who invented the programming language Erlang - explained the asymmetry of programmer's psychology he experienced himself:
"I think your brain works in 2 different ways. When you're working on the program, you're like cached in the program, and you see no need to explain it because it's bloody obvious and so you write any documentation...."
However, documenting code is expedient.
Joe Armstrong further expresses it thus:
"... And when you cached it out, you wish there was some documentation because you can't understand it at all."
Furthermore, documentation is crucial to the team, the shareholders and the end-users of a product. It is required during the different phases of the product development cycle as it keeps everyone involved in the process up-to-date with the development process. Also, it makes code optimization easy.
What is Technical Documentation?
It is simply the document that carries all the information and data about a product or service. It shows how to use and maintain the product. It is a tool for knowledge transfer.
Categories of Technical Documentation
Technical Documentation is generally grouped into categories based on function. One category describes the product in development while the other describes the development process.
1. Product Documentation: This type of documentation describes a product and provides instructions on how to use it. Types of product documentation include end-user documentation, system-administrator documentation, product requirement document, user experience (UX) design documentation, source code documentation, API documentation and maintenance guide documentation.
2. Process Documentation: This type of documentation records the development and maintenance of the product. Types include coding, design, working ideas, metrics, reports, minutes, test schedules, and project plans.
Tips and Best Practices for Writing Technical Documentation
- Have a plan: Carefully consider areas to be covered, do your research and involve team members across departments if necessary.
- Understand your audience
- Be concise
- Have a consistent style
- Make it as interactive as possible with images and clips if possible.
The Importance of Technical Documentation
As mentioned above, technical documentation is essential to the programmer, the team, the stakeholder and the user of a product.
The following are some reasons to document code:
- It provides crucial information about a product or service to users.
- It helps users achieve their goals and saves the company time and money.
- It helps keep the team up-to-date, thereby enhancing productivity.
- It helps to manage to maintain and optimize a product.
- It helps make the software development life-cycle process transparent and manageable.
- It can help improve user adoption, experience, and retention.
Examples of Great Technical Documentation
You can check out the following technical documentation to get an idea of what to do:
- GitHub interactive documentation.
- Apple iPhone end-user documentation.
- Google Apps Script technical documentation
Check Further reading for tools.
References
https://clevertap.com/blog/technical-documentation/
https://www.indeed.com/career-advice/career-development/technical-documentation
https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/
