Most of the teams are still in a never-ending quest for the documentation sweet spot. The place that you don’t have spend too much time maintaining it, yet it brings a lot of value and is up to date.
For some the starting point was from agile manifesto or software craftsmanship misunderstanding, which is not-documenting at all. Others decided to build a comprehensive documentation, soon to discover it is a challenge to keep it up with the reality (which is the code).
There is a better way to build a good Developer Experience. I will share several options, that you may take advantage of, including:
- partially executable documentation without (non-docstring)
- human- and machine-readable HTTP API documentation
- automated tests as documentation
The perfect audience
- writes code long-term (that will be used for at least 6+ months)
- creates automated tests (or code snippets to verify that the code works)
The presented patterns shall bring value to developers regardless of the domain.
Attendees should learn of how to reuse code between tests and documentation. This will improve their documentation and keep it always up to date.