Software Documentation: How Much Is Enough?
Date: Nov 9, 2021
Book Excerpt is provided courtesy ofAddison-Wesley Professional.
Principal consultant and experienced software team leader Karl Wiegers outlines when you should record requirements and other pertinent information while developing software.
There's no single answer to how much documentation a software project team should create. But the key point to keep in mind when deciding whether or not to document some piece of information is this:
The cost of recording knowledge is small compared to the cost of acquiring knowledge.
一些人不惜花时间写requirements. Maybe they're afraid of analysis paralysis, getting caught in an endless trap of trying to write down and perfect every bit of knowledge. But the hard part isn't writing requirements—it's figuring out what they are. Don't use the fear of paralysis as a rationale for not recording essential requirements information in some suitable form.
Similarly, people sometimes are reluctant to write a project plan. Again, the hard part is thinking through all the activities needed to complete the project: identifying deliverables, tasks, dependencies, resources needed, schedules, and so forth. Writing a plan is transcription. It takes time, yes. However, it takes less time than trying to communicate the same information to multiple people in a consistent way throughout the course of the project. It's also less error-prone than having to remember all that information accurately.
People sometimes must reverse engineer information from an existing system to figure out how to modify. Recovering knowledge through reverse engineering is tedious; doing it repeatedly is inefficient. If you write down what you learn, that information is available if you or anyone else needs to go back to it. This recording is a way to incrementally accumulate knowledge about an ill-documented system as you work on it. You can also begin building visual analysis models from recovered knowledge to provide alternative views of system information. Partial information—if it is accurate—is better than none.
I would decide not to record that newly-recovered knowledge only if I were certain that no one—including myself—would ever need to work with that part of the system again. As I'm not skilled at predicting the future, I prefer to represent knowledge in some persistent and shareable form.
If every project stakeholder were privy to every discussion, interpreted information identically, and had a perfect memory, you'd never need to write anything down. Alas, this is not reality. Thoughtfully crafted documentation serves as a group memory, a resource to which team members can refer across space and time.