If you join a team I’m working at, you’ll probably hear this from me on your first day:
“…we’ve done our best to write documentation, but I know that it could be way better. Could you help out? It would be awesome if we could improve the docs together while you’re getting to know the project: that’s the best time for it!”
I’ve done this for years now — and no, it’s not because I don’t want to write documentation myself.
I want new team-members to take a stab at improving the docs because it helps both the project and themselves.
Transfer knowledge faster next time. You’re going to have rounds of questions and answers as part of the onboarding anyway. Why not write some of them down along the way? Write it down as a FAQ section in the README file as you go, even. The next time a new colleague comes along, you’ll spend less time on their onboarding process.
Learn by teaching. When you document software, you are in effect teaching future readers. It’s well known in pedagogy that teaching what you are learning makes your own learning process more effective.
New people == fresh eyes. New people bring a fresh perspective. Having the new person help you describe your environment back to you will help you notice the broken windows again.
If you can’t describe it, I probably need to improve it. Helping a new colleague describe the architecture can be revealing. If this turns out to be hard to do, that might be a symptom that your project is messier than it should be. On some level you may be aware of the problems already, but drilling down into the problems during documentation can really drive it home. “Wow, this module is really tricky to describe. It does a bunch of things that don’t belong there. And it’s hard to change and maintain too, come to think of it…”
Different people have different strengths. What is obvious to me may be new to you. And vice versa. Together we cover more bases. You might gloss over some steps, patterns or tools that “everyone knows” (I’ve certainly done that in my own documentation). If the new colleague has a different background and points out these non-obvious bits, this will be fixed. “Ok, maybe I should provide complete examples of these magic bash commands…”
Repeated editing improves ALL writing. The first draft of anything is usually crap. I’ve written documentation too quickly, or in a single sitting, and when I go back to those docs they’re barely readable. Multiple passes by several people will make your documentation more pleasant and useful for future readers. One of those readers may be yourself, years down the road.
Set a clear expectation from day one. Many of us procrastinate when it comes to documentation. Doing it up front when you come onboard makes “document early” more likely to be a part of the project culture. Well, maybe. One can hope. 🙂
Help each other leave the campsite cleaner than you found it!