I strongly believe that proactively keep documentation up to date is not worth the effort.
Here is what I recommend in my teams:
- There’s an onboarding guide that is usually only updated when new people onboard. If something is not right they raise it and their onboarding partner fixes it.
- When someone shares a technical document/RFC we add it to a central repository with a creation date on it. These are point in time and usually not updated but still useful for new hires.
- We sometimes do onboarding sessions to walk through the architecture, these are recorded and added to the central information repository.
Note that in the things I wrote above there’s a mix of up to date content and slightly outdated content, ultimately the code is the source of truth. It’s not worth spending time writing docs that no one is gonna read.
Funny, I just posted the exact opposite. And find that everyone reads my docs, and comes back to them frequently as they work in different areas of the codebase. Of course, we are a remote team who swaps people in and out often, so onboarding is not a one-time event where you have partners to hold your hand. If you really only onboard once and don't have a fast-growing team, I could see where the needs would not match up and we'd both be correct for our own situations.
And do you go back and update all documents whenever something changes? If you’re swapping people around every month I agree that you must keep everything written down, happens a lot in projects that bring consultants in. But if you have a core team of people and you get 2-3 new people per year then you should be more relaxed about it.
Yep, we do. It is part of the process just like testing. For the most part, it is not painful - most features are variations on existing patterns, and don't need updates. When we do code up a new pattern, we update docs.
And you are correct - we use consultants on the team, and hire in gig workers for small tasks on a regular basis. When I worked on a small core team without much churn, I did not do any of this.
- There’s an onboarding guide that is usually only updated when new people onboard. If something is not right they raise it and their onboarding partner fixes it.
- When someone shares a technical document/RFC we add it to a central repository with a creation date on it. These are point in time and usually not updated but still useful for new hires.
- We sometimes do onboarding sessions to walk through the architecture, these are recorded and added to the central information repository.
Note that in the things I wrote above there’s a mix of up to date content and slightly outdated content, ultimately the code is the source of truth. It’s not worth spending time writing docs that no one is gonna read.