3 ms·
Keep your product documentation in the same repo as the product code and the convenience of being able to update it at the same time will manifest into more up
by candiddevmike 3y ago
Keep your product documentation in the same repo as the product code and the convenience of being able to update it at the same time will manifest into more up to date documentation. Have the tech writers part of code reviews and rewrite things if necessary.
Don't compartmentalize your product and the documentation for it. Developers don't hate documentation, they hate opening 15 PRs to get shit done.
- tbragin 3y agoAmen, especially for reference documentation, such as API or functions / SQL commands (e.g. for a database product). Those docs should be checked in with the code, and PR should not get merged if the docs are not ready.
- euroderf 3y ago"Docs As Code" is a concept in this space. It mostly assumes the use of Markdown & friends. Then it's probably left to the tech writer(s) to (a) automate the aggregation & assembly processes, and (b) make sure that their edits make it back to the code repos. AFAIK there's not a nice open source solution (or even toolset) for this.
- candiddevmike 3y agoI use Docsy with great results: https://docsy.dev https://docsy.dev, e.g. https://github.com/candiddev/homechart/tree/main/hugo/content/docs https://github.com/candiddev/homechart/tree/main/hugo/conten...
- euroderf 3y agoDoes it (can it) work as something like a CCMS ?