No post body was provided.
Ask HN: How do you keep your technical docs in sync with code?
1–10 of 14 posts
Re: Ask HN: How do you keep your technical docs in sync with code?
#2Don't have technical documentation -- instead have
- 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
Re: Ask HN: How do you keep your technical docs in sync with code?
#3Don't have technical documentation -- instead have - 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
How is design docs different from technical docs?
Re: Ask HN: How do you keep your technical docs in sync with code?
#4Don't have technical documentation -- instead have - 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
How is design docs different from technical docs?
They are not updated, on purpose. This is the design now.
Re: Ask HN: How do you keep your technical docs in sync with code?
#5We don't. Everything that is not part of the code will just get out of date.
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.
Re: Ask HN: How do you keep your technical docs in sync with code?
#6With annotated, declarative step-based YAML integration tests. They autogenerate how-to markdown documents via a jinja2 template:
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.
Re: Ask HN: How do you keep your technical docs in sync with code?
#7Don't have technical documentation -- instead have - 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
How is design docs different from technical docs?
Design docs are for the developpers. Technical docs could also be for the users, by e.g. ending up in some manual or so.
Re: Ask HN: How do you keep your technical docs in sync with code?
#8Earlier quoted context omitted.
How is design docs different from technical docs?
They are not updated, on purpose. This is the design now.
Is that ideal for example for onboarding new developers? Our challenge is we are are starting to hire but we also move very fast and every time we refer people to our onboarding docs, they come back confused because some essential thing is now deprecated.
Re: Ask HN: How do you keep your technical docs in sync with code?
#9Earlier quoted context omitted.
How is design docs different from technical docs?
Design docs are for the developpers. Technical docs could also be for the users, by e.g. ending up in some manual or so.
Sorry. In that case I used a bad word. I probably should have said internal docs that explain some specific flow or behavior of the system. A good example is one that onboards new devs.
Re: Ask HN: How do you keep your technical docs in sync with code?
#10Earlier quoted context omitted.
They are not updated, on purpose. This is the design now.
Is that ideal for example for onboarding new developers? Our challenge is we are are starting to hire but we also move very fast and every time we refer people to our onboarding docs, they come back confused because some essential thing is now deprecated.
Hence clear code with comments on the sharp corners