In this Article I am talking about comments but also check out my article on comments.
Thoughts on documentation
Developers hate writing documentation. And I understand it. Writing it is very hard. Reading bad documentation is never done because nobody reads it anyway. When you are working on a project and you are knee deep in the project, you know everything anyway, why document?
I am a fan of good documentation. But to understand, what is good documentation, lets talk about the different types of documentation.
Types of documentation
Inline Documentation: Inline Comments
Comments within the code are also one type of documentation that is often overlooked. You can read my article about them here.
They are used directly within the code to clarify things for the reader.
In a nutshell:
- They are very close to the code
- They are very detail oriented.
- You won't read them in advance when starting a project.
Inline Documentation: Doc Comments
These are used within the code to document higher level components like functions, classes, modules. Quite often, they rely on a standard and can be used to generate documentation in a dedicated place.
- Close to the code
- Describe the components within a codebase on a higher level.
- You might read them one by one when using or working on a component or skip through the high level components like modules when starting on a project.
API Documentation
This one is very obvious. Documenting the API a library or service provides makes total sense. It's the best way to communicate how to use it to a consumer.
- Often generated within the code by annotating web handlers / controllers.
- They only document the outer interface of a service or library
- You might read them when using something new or to look up details.
Pitfalls: Often the API documentation does not contain a complete example on how to use it and how to combine multiple requests. This is very helpful.
Readme Documentation
They usually describe one service in a repository. If you have multiple services in one repository, there might be multiple readmes, one per service. Most often they describe what the service is supposed to be doing and how you get started running and developing it and also contain pointers to further documentation.
- They are close to the code
- The describe the purpose of the service and how to get started
- You will read them when you get started developing.
Pitfalls: If the documentation in the readme is to detailed, it will get out of sync with reality very quickly. Therefor it is best practice to only document what is stable and also have every new developer update the readme when they onboard.
Application Architecture Documentation
This is where documentation starts to get more visual. If the application is not trivial, it is very helpful to document the application architecture. Usually this emphasizes the layers, bigger modules and direct external dependencies like caches, data store, queues, other API's etc.
- This documentation is not very close to the code anymore as it is high level and therefore can not be autogenerated in a meaningful way.
It has to be maintained by hand when something changes.
Pitfalls: If this is to detailed it will be wrong very soon. If a new dependency is added, often it is forgotten to add it in this documentation. It is very useful to use this document when onboarding new developers and periodically have a team mob-session to update it. This refreshes memory and keeps it more or less up to date.
System Architecture documentation
Depending on the size of the system this part documents the services communicating with each other within the org, the department or the team. Sometimes there will be multiple System Architecture Documentations to limit the scope you have to understand. Sometimes it makes sense to add more documentation for specific parts of the architecture.
- Very far away from the code, focussing on very high level and the communication between systems.
Can be augmented with automatic services that analyze services talking to each other and draw diagrams like Backstage.
Pitfalls: If this is to detailed it will be wrong very soon. If new services are added, often it is forgotten to add it in this documentation. It is very useful to use this document when onboarding new developers and update it accordingly.
Infrastructure & Deployment documentation
It is very helpful to quickly understand where and how a service is deployed, when are which tests running and have a visual representation of that.
- Where is the service deployed? What infrastructure is involved.
- What is the process of deployement, how does the pipeline look like? What checks are running etc.
- Sometimes the visual pipeline documentation of Tools like Github Actions, Jenkins or Concourse can be good enough or helpful and should be at least linked.
Process Documentation / Runtime Views
Every application and every system contains processes. Some more complicated than others, some more important than others. What happens when a user registers? Which services are hit? Are workers involved?
Pitfalls: Do not fall into the trap and try to be very precise or try to document each process that happens. Practice MVD - Minimum Viable Documentation. Focus on the most important and most used/changed processes.
Decision Documentation
Documentation and also Code do not document the history of an application. It is also not possible to economically document all bits and bobs of a system. Therefore it make sense to focus on decision documentation that is easy to search.
Benefits:
- It is obvious that it was just a moment in time, it might be out of date
- It documents the history, the reason for the decison and also why alternatives have not been chosen.
What kind of decisions should be documented?
- Architecture decisions
- Tech decisions (Language, libraries, frameworks..)
- Process Decisions.
Pitfalls: In a software projects are a lot of decisions made on a daily basis. It is not easy to see which decision is a documentation worthy decision. in the beginning, decisions should be discussed with the team and documented to get a feeling what are bigger decisions.
One example for Decision Documentation are ADR - Architecture Decision Records.
Here is an example.
MVD - Minimum Viable Documentation
Have you heard about MVD - Minimum Viable Documentation? No? Don't worry, it is a term that I just made up.
Just like with MVP - Minimum Viable Product, the idea behind MVD is to be very mindful about what amount of documentaton actually solves the problem that it aims to solve. Documentation aims to help you, when onboarding into a new project or during the work on a new project to understand specific parts to you do not have in mind. Too much documentation will just clutter your mind. Therefore documentation should be optimized for two use cases:
- Onboarding: Optimize for quick and high level understandability of the system and application.
- Look up: Optimize for searchability and correctness. Accept incompleteness in the documentation but make it obvious.
For Onboarding, good documentation should focus on high level and visual documentation. For Look Up, documentation should additionally focus on decision records and relevant process documentation.
Documentation should be as lightweight as possible - do not use big templates that are filled with irrelevant filler material. It should be easy to read, search and edit.
Guidelines for good documentation
- Be as transparent as possible on what documentation exists and make it hard to miss.
- Kep it as close to the code as possible (what you see is what you know exists)
- Only document things that are very stable and do not change too much. The more something changes the more time you need to spend on keeping documentation correct.
- The more documentation exists, the less people will read it. Practice MVD - Minimum Viable Documentation.
- Embrace fuzzy Documentation for things that do change.
- Document what somebody withour prior knowledge would need to understand the system quickly, without going into details.
- Use onboarding of new developers as a documentation update tool. Use the High level Application Architecture, System Architecture and Deployment Documentation for onboarding and update before and during onboarding.
- Do periodic team mob-sessions to refresh the memory on the high-level architecture and also to update it if it changed.
- Try to standardize the way documentation works across the organization.
Documentation frameworks
- arc42 - arc42
- The C4 model for visualising software architecture
- ADR - Architecture Decision Records
I prefer arc42 - it not only helps you with architecture and process diagrams but also is a great tool to use when starting a new project. It also covers risks, assumptions, stakeholders, decisions made etc.
Top comments (0)