Everybody speaks that documentation is important for development. In the end when a project accumulates hundreds of pages with documentation, nobody wants to update it because it’s boring, difficult and need time which cannot be converted to value for customers. The documentation becomes outdated and lose its point. This is the “dead-end” of documentation process which I saw several times. In recent projects I’m following the idea about documenting only static information, avoiding schemes, rules and other stuff which is a matter of habit in the team even if it seems like a static information. I accumulated in this article some thoughts about what should be documented, how and when to prevent the documentation “dead-end”. This is just a recommendation and points which might be taken into consideration.
Kinds of Information in Projects
Usually I saw division of information by areas which it covers. The good example of such division below[1].
| Step-by-Step Walkthroughs | Also called Guides, How to’s, or Examples, Quick Start Guides. |
| Product feature documentation | This is lists all the features and settings without really any real world examples. Often the help button inside the software points to sections of this document. |
| Troubleshooting Documentation | What to do when a failure occurs. Where are the logs and how to read them. How to turn on or increase logging and debugging. |
| Knowledge base | Problem, cause, resolution; frequently asked questions (FAQ), and forums. |
| Code, API, or SDK Documentation | |
| Internal Development Documentation | Such as code and development documentation, internal only features use by developers and/or testers, architecture documentation (Note: For open source projects this information is usually public) |
| Real life customer implementations | Examples of how a company has a product implemented in real life. |
| Marketing documentation | Basic over views of the value the software has for the company, ROI claims, general feature lists, costs, etc… |
This division is good, but doesn’t shed a light on efficiency of this documentation and don’t tell you how develop it in an efficient way. I can spend hours on generating development documentation which will never be used. So that I use also other attributes of the documentation. When the first type of categorization will tell you how your wiki catalogue should be organized, the second one will shed a light on whether you need to document the information or not. This aspects can be used to build your own approach for documentation.
| Size | Small | This kind of information can be easily remembered with all important aspects. You use it every day by its nature. |
| Big | You cannot hold all important aspects in your mind by any reason. This information might be rarely used or just too complicated. | |
| Relation | Internal | This is everything which the team is responsible for. For example, code repositories, build environments. |
| External | Everything which the team is not responsible for. This might be deployment servers, cloud resources, other projects. | |
| Duration | Static | The information of this kind tends to be unchanged for a long period of time. |
| Dynamic | Such information tends to change quickly or without your control. |
These kinds altogether will give you a clue when and with how many details the information should be stored in your wiki. But sometimes you should also account how information is important to your project. Trying to summarize the vision I would recommend to use this decision matrix, although, which is very simplified.
You can find that some times the matrix gives you “Yes-Yes-Yes” or “No-No-No” which means you whether should or should not document the information. This strong “Yes” also tells that the information should be updated as soon as possible and have all details that you have. In other cases the matrix gives you “Yes-No-No” or “No-Yes-Yes” which means it’s better not to document or better to document respectively. You also should consider the importance of the information in such cases.
Real Life Example
Let’s see how this matrix works using a real example, my projects where I’m in. My project has a distributed team with several GitHub repositories, Jenkins, several production and test servers. Our deployment process is partly automated. We have several web and windows services, two web applications which we’re improving, fixing, monitoring and deploying. All these systems we’re integrating with other services of our company via different communication channels (files, messaging, web requests). We’re conquering new geographical regions and our customers always give us ideas about system improvements. The system is very flexible and have a lot of configuration aspects which we might forget if they are rarely used. That’s all.
The information about deployment environments, build servers, databases is internal because we’re deploying and maintaining them on our own. It’s also static because it won’t be changed in a year. It’s big because of too many details which we’re not using every day. In such a case “Static-Internal-Big” the matrix gives “Yes-Yes-Yes”. So that it’s no doubt should be documented. Another example of the “Static-Internal-Big” information is the on-boarding documentation. This is what every new comer should read when he joins to the project. Code repositories, credentials also belong to this category.
There is a kind of information which might be attributed to static or dynamic depends on details you’re about to document. These are feature and algorithm descriptions. In most of the cases the high level overview is static, but their details of implementation may vary too fast. For example, function names, variable names, detailed algorithm descriptions.
I also want to mention such information like code conventions and rules. Most of the time it’s dynamic information or quite small. It’s small because can be easily learnt. There is a project manager who will remind you about rules. You’re keeping in mind code conventions during day-to-day work and it may naturally evolve. So that relax and don’t waste your time on documenting it, because you’ll never lose this information.
See Also