News for hackers. Stuff that matters.

A comment on Ask HN: How do you keep your technical docs in sync with code?.

Re:Ask HN: How do you keep your technical docs in sync with ... by jjgreen on Monday September 18, 2023 @05:58AM (#37554198)
Don'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

[ Parent | on HN ]
Re:Ask HN: How do you keep your technical docs in sync with ... by ardalanpouya on Monday September 18, 2023 @06:01AM (#37554223)
How is design docs different from technical docs?
[ Parent | on HN ]
Re:Ask HN: How do you keep your technical docs in sync with ... by jjgreen on Monday September 18, 2023 @06:04AM (#37554241)
They are not updated, on purpose. This is the design now.
[ Parent | on HN ]
Re:Ask HN: How do you keep your technical docs in sync with ... by ardalanpouya on Monday September 18, 2023 @06:12AM (#37554292)
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.
[ Parent | on HN ]
Re:Ask HN: How do you keep your technical docs in sync with ... by jjgreen on Monday September 18, 2023 @06:22AM (#37554334)
Hence clear code with comments on the sharp corners
[ Parent | on HN ]
Re:Ask HN: How do you keep your technical docs in sync with ... by Double_a_92 on Monday September 18, 2023 @06:09AM (#37554274)
Design docs are for the developpers. Technical docs could also be for the users, by e.g. ending up in some manual or so.
[ Parent | on HN ]
Re:Ask HN: How do you keep your technical docs in sync with ... by ardalanpouya on Monday September 18, 2023 @06:14AM (#37554306)
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.
[ Parent | on HN ]