Hey Everyone, I would be thankful if you could give me feedback on the problem and solution that I work on that is described in the blog post below:
This post should be as short as Tech Leads’ time committed to working with documentation. In reality this means a few lines (because Tech Leads have better things to do) but in practice it will be long and painful to read. Because that is how the current experience with documentation looks like.
First of all - who is responsible for widely defined software project documentation? Developers have self-documenting code. Product Owners and Project Managers do not work with code on a daily basis so they cannot create documentation. Many times the boring tasks of writing documentation goes to a) Tech Lead b) Senior Software Developer - because they see the value in having at least some of it. Sometimes it is a business requirement that they are responsible for. Possibly also because they have to answer lots of questions on a daily basis and they operate as a walking knowledge base. Instead of answering the same question multiple times they can say RTFM but they need to have FM.
If Tech Leads or Senior Developers decide to write down the knowledge they have in their heads there are still the following issues:
-
who will update the documentation once new features are introduced?
-
how will we ensure that the documentation doesn’t get out of date?
If Tech Leads want developers to write documentation they have to be able to answer the question “what if the code changes?” because without it every developer will think “why should I write documentation if it can go out of date the next day?”. Tech Leads cannot make demands without giving tools and reasonable processes. Developers’ time is too expensive to be spent on excessive documentation maintenance, caused by incorrect tooling.
Problem:
Tech Leads need to have some documentation (for various reasons). Tech Leads cannot spend a lot of time writing documentation.
Developers can write documentation in a distributed way (every developer has some unique project knowledge in their heads).
But they need to be sure that their time is not being wasted and that they will not spend most of their time on this task.
Current Solutions for Tech Leads:
- Don’t write documentation at all, answer questions on a daily basis. This solution will work to some extent! Especially in small companies where you do not have so many stakeholders.
- Auto-generate documentation from code. Only good for API-like documentation but will not work for business/product documentation.
Solution that IMO makes more sense:
Have a system that links documentation with code. If there is documentation that will change once the code changes, link it with code.
The links have to be automatically updated, for example once the filename is being changed but the code content stays the same. Or if the linked method/class is being moved in the file, the links should be updated automatically as well. You can either create a software for this on your own or use existing software on the market (like HastyDocs).
The good and the bad thing about software documentation is the following. No one will blame you for having none or limited documentation. The same was common 20 years ago with tests. No one blamed you for having no or limited tests - because every team wrote good code which didn’t have bugs so it didn’t have to be tested 
The same way today, every team writes self-documenting code which everyone can read in order to understand what is inside… 
Let me know in the comments if I’m missing something and what you think about linking docs with code.