We 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.
I like the idea of timestamping docs. How often do you run into something being "annoyingly out of date"? Asking because it happens alot for us with onboarding docs specially. I am trying to find out what we are doing wrong
This is a very interesting idea. but I foresee two challenges here: (1) it sounds like alot of maitnance to keep a set of annotated tests that updates docs. (2) this does not sound like a solution for a company which produces handful of system behavior explaining docs on a daily basis. it looks like it is more so intended with low level documentation
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
Double_a_92|2 years ago
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.
ardalanpouya|2 years ago
hitchstory|2 years ago
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.
ardalanpouya|2 years ago
jjgreen|2 years ago
- 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
ardalanpouya|2 years ago