Documentation is always that one thing, you probably don’t like to update. No matter of this, fact that it is a must have in every project can’t be denied.
During development I have tried multiple solutions of how to write and when. Mine first project was even without any docs. However that was a big mistake and afterward I have decided to start writing anything. That “anything” also was a big problem, because I didn’t knew of “what”, “where” and “how” to write.
Found own way to document
1. What: have a structure.
2. Where: near the code.
3. How: continuously with reviews.
Those three points and it’s solutions seems to be the best compromise between businesses and technical aspects.
Why do I need a structure?
Where to search for an interesting information is a key to fast and clear communication during handover process. This knowledge is also a direction to quick resolve problems during maintenance stage. Sections that are written in a structured way will be very easy understandable by a group of people that are target readers. In the end, as a developer that is responsible for writing most of documentation parts, I will know where to write without additional thinking.
1. Each section is written by a responsible person.
2. Remember about that who will later on read this documentation and keep details hidden.
3. Write from general to detail.
4. Don’t be afraid to write less.
5. Repeat yourself in case of need while writing parts for different target groups of readers.
Most important reader groups
1. Business: PO, PM, CIO and anyone who is not technical.
2. User (User Guide)
4. Operations (Support)
4. External Developer (if you have API or your app is pluginnable)
5. Developer who may write after you
Based on known reader groups, can define what kind of documentation is a must have in a project. It would be good if each group have separate documents. Most probably CIO may not want to read about API. External developer who will write clients to your app will not be interested in budget. Just keep for reader only this what is for him.
More about “Documentation Near the Code” and “Continous Documentation Process” soon.
Git4C – Your code in Confluence (introduction) may be a part of complex solution for managing of documentation.