A reader responded to yesterday’s email about which way to write documentation is the best, or at least which is my preferred way.
The short answer is, whichever way people will actually adopt.
You can write the best documentation on the planet, but if no one updates it after you leave, it’s effectively useless. So be sure you have client buy-in before choosing your path.
If your client prefers design documents, then by all means, use design documents. If they like user stories, well, you know what to do.
Now, what if they don’t have a preference? First ask them if they really need documentation (Don’t snicker, some clients don’t really care). If the answer is yes, then provide the pros and cons of each approach and make a decision together.
OK, I can already hear you screaming at me for a direct answer.
I prefer
- Design documents for smaller teams/projects
- User stories for larger teams/projects
Why? It’s easier to update a single document when there’s only a single architect working with a small team. But it becomes a big bottleneck for larger teams and projects.
The takeaway
The best way to document is to select a way that everyone agrees to and will continue to use once you’re no longer around.