Ask HN: How do you keep your technical docs in sync with code? |
Ask HN: How do you keep your technical docs in sync with code? |
It's just best to reduce external documentation, or at least bundle all in one place.
What works best is just creating a rough sketch of the idea, and store it somewhere next to the code with a datestamp. So it's clear that it's out of date, but if you really need some hint of how it was intended to work you can still look at it. (That is usually some class diagram, or a word document with explanations...)
Or it's just kept up to date by being used. E.g. we have step-by-step instructions for certain tasks, that devs occasionally need to follow. So if things get annoyingly out of date we just fix the instruction that has become unclear with time.
https://github.com/hitchdev/hitchstory (there are a few toy examples listed there)
Depending on the app the docs might also embed artefacts generated under test - e.g. screenshots from playwright.
There are examples there to demonstrate use on any level - e.g. to create unit-test level tests for a library or that generate code docs for programmers or playwright e2e tests that generate user-readable how to docs.
The interaction code requires maintenance but a lot of it very boilerplate. E.g. you need a function to interpret the "click" step to do the proper playwright click or drag-drop but it should function more or less the same for everybody.
- design documentation which has a date, and it is understood that it is correct at the time of writing but will age and become less accurate with time
- clear code with comments on the sharp corners