Good documentation is must and it must be source code. I use plenty of tools/langs for it - PlantUml, markdown, matjax, mkdocs, sphynx etc. Docs site should be

Good documentation is must and it must be source code. I use plenty of tools/langs for it - PlantUml, markdown, matjax, mkdocs, sphynx etc. Docs site should be among deliverables along with its CI/CD and automatic tests. One other important benefit of keeping it as a source code is that a team on a feature branch can see diffs on funspec and easily follow the iterations on it instead of looking at one gigantic Word file as usual which is anything but practical for quickly determining what was changed in previous few days. The main problems appears to be: - When to start documenting - How to keep it up to date. This means that there need to be some processes, some good tools and ideally executable documentation (ansible, jupiter...). For example, I like to keep readme.md in each folder describing the purpose of that folder and what files are expected to be in it, in what format etc. Then during build, I can simply concatenate this into technical docs appendix and/or link directly to appropriate readme when specific section needs details. This means that in technical/functional docs there is only high level picture that rarely changes, and hence is more up to date and stuff that changes often is closer to the source of change. I also think that keeping ticket numbers inside README.md as a reference is good practice, and keeping tickets itself connected. So I need entry point into PM tool and then I can follow from there if I need even more details. For architectural decisions that are not obvious from the tickets one can use ADR in repository (architectural decision records) that are great for on-boarding and reminding on why we took certain path. Documentation is hard, its literally a full time job. Its usual I spend weeks on projects automating documentation. The latest setup I use puts everything in single docker image and I spin it on each new project on CI level to build static site [1]. I also have detailed Gitlab procedures on how to create tickets that export well to the changelog. Visual Studio Code team nailed this IMO. [1]: https://github.com/majkinetor/mm-docs https://github.com/majkinetor/mm-docs