Writing Good Documentation
Students often think that the most important part in learning Computer Science is coding and solving problems.
Therefore, most students only focus on the code and ignore everything else.
Although they can solve the problems, their codes are difficult to understand and maintain.
Documentation is the solution for these cases.
What is Documentation?
Documentation is a text
go along with computer software to illustrate how to use the code, and/or explain the meaning of code.
Why Documentation?
- Knowledge Preservation: ensure effective knowledge transfer.
- Quality increasing: make project well-organized.
- Make your project consistent overtime.
How to write Documentation?
- Determine what information should be included
- Determine where to locate your documentation
- Choose appropriate tools based on your programming language.
- Know who will read your documentation
Tips for writing good documentation
- Visualize your documentation
- Offer examples in your documentation
- Make documentation easy to understand
- Figure out impediments
- Test your documentation
- Learn from other documentations to improve yours
Try it yourself
- Resources:
- Here is a good overview about documentation.
-
Go here
for a good example of writing documentation
- Practices:
From now, you should start to write documentation for your code.
There are a lot of helper tools such as RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, or HelpLogix. Good luck!
