Fundamentals of engineering documentation
Our tiny startup is growing. We had one new engineer join our team every Monday for the last 3 weeks. The new hires were thrilled to join and wanted to start contributing right away. But much to their disappointment, they could barely get to setting up code repository on the first day. Like an engineering ritual, during the stand up next day, the new hire complained about the documentation.
Why is documentation never good enough?
Because most documentation is written without putting much thought around its intent and structure.
You can largely blame this to the fact that we are never taught about it in any CS fundamentals class. But it's never too late to learn 😊
Documentation 101
Documentation is a very vague term. It includes everything from API docs, design docs, how-tos, readme, guides, tech-specifications etc. But it can be broadly classified in 2 categories
Theoretical documentation
As the name suggests, theoretical documentation is written to help readers grasp concepts and structure of the project. It talks about abstract and finer details but it is not actionable. It can be further classified into 2 categories -
- References
- Discussions References include your API docs and technical specifications. They are very information oriented. However, discussions are meant to illuminate readers. They talk about fundamental concepts, designs and history of the project.
Practical documentation
Practical documentation is meant to be actionable. It helps readers do something real with your project. There are 2 categories of it -
- Tutorials
- How-to-guides Most engineers think these are the same things, but they are not. The fundamental behind a tutorial is "learning by doing" vs behind a how-to is "help me do this as fast as possible".
How to structure your documentation? and why?
Generally, all documentation should be in one place. But more importantly, it should be grouped by the 4 logical sub-categories above. If you do that, your documentation will be far more effective and maintainable. Readers will discover it better and writers can easily spot what area needs more documentation.
If you are willing to learn more about this, checkout this site - documentation.divio.com