Here’s how to keep your engineering docs up to date.. 1. Keep docs in the same repo as the code => If it’s in Notion, it will be forgotten. 2. Update docs in the same PR as the change => Docs should go through code review too. 3. Write a ticket for doc updates => Don’t rely on a PR checklist. Devs skip them 4. Assign a “docs on-call” each sprint => One person spends a couple hours reviewing and updating docs Any other ideas?
Definitely keep in the same repo. Standardise names too - ARCHITECTURE.md, TESTING.md, REPO_STRUCTURE.md That way everyone know where to look, where to edit. One source of truth. Potential use of LLMs too - have a pipeline step "Compare the code to the markdown files and report on any potential discrepancies"
If you ignore all but one of these tops "Keep docs in the same repo as the code" will have the biggest overall impact in ensuring they are maintained. Having the docs next to my code, using markdown to edit in my editor vs having to login and update confluence or notion is the biggest win.
Yeah I think this is key -- doc systems outside of the codebase end up being extremely flakey and easy to become out of date.
Great tips!
Chelsea Troy has a good article on this. https://chelseatroy.com/2021/09/14/the-art-of-documentation/
As far as possible, docs should be generated from the code. Technical API documentation can be completely auto generated. It's harder with discursive docs ("how to" guides and things like that) but the content should at least be close to the code in the repo, and in a form that devs and technical writers can easily update and review. Have an automated process for capturing and refreshing screenshots (one of the worst offenders for going out of date).
These are good insights. How does the tool you’re building help?
I’m currently use something like “documentation first” approach. So docs are always the first thing to change, and tasks and design is followed by docs or updated in the same stage
Add a deployment step where ai reads the docs vs the code and bitches about discrepancies ? Shotty not being the one to pilot that idea. Lmk how it works
Cloud and DevOps Specialist | Principal Consultant @ Slalom
9hIt would be really cool if the major git providers providers provided a WYSIWYG editor that checks into the repo as part of code, and show up as part of merge/pull requests. As supposed to what we have now, with the likes of confluence and others which is always having to play catch-up with the code. Markdown works great for developer short docs but if non-devs want to look and edit supporting documentation, then we need a better solution that can get updated with code changes and visible in changes during code review. I make the assumption here that the document writer is either a human or an agent. Regardless a human still needs to review and maybe edit.