Documenting the Process (and Hating Every Minute of It)
- Documentation as Discipline
- Documentation Gone Wrong
- A Clear Departure from the Past
- Finding the Right Balance
- Staying Focused on Discipline
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
After 10 years of project work, I've noticed three main reasons that people create documentation:
- To exercise discipline when approaching a problem
- To show evidence during an audit
- For historical purposes (for use on later projects, for training, and so on)
In general, I'm a fan of using documentation to exercise discipline when approaching a problem, and I'll create documentation to provide evidence when the project context calls for it, but I hate documentation for the sake of documentation (also known as "historical purposes"). I don't like creating it, reading it, sorting through it, or checking it into or out of a SharePoint site. I've worked on regulated projects in which documentation was over 50% of the effort. And I've worked on "agile" projects where we were lucky if we had three lines describing what a feature should do or how we should test it.
In this article, we'll look at a struggling test team and discover how documenting some simple things helped to create alignment and move the team in a new direction. The trick is to move away from documentation for historical purposes and move toward documentation to exercise discipline when approaching a problem.
Documentation as Discipline
I know a project manager who tells people new to his team to "think on paper." He knows that software development problems are difficult and that solving those problems requires time spent in research, comparing options, and prototyping. He asks people to "think on paper" so that he can see what progress is being made as the work is being done. He told me once, "When I know that you know how to think, you don't have to think on paper any longer."
Documentation can force you to think about different aspects of a problem. For example, when a programmer goes through the process of creating UML diagrams for a new feature to be implemented, he's forced to think through how components will interact, how code will be structured, and so forth. When I test, I document my test ideas because it helps me to think about coverage and risk. I make long lists that I share with other people to get their feedback. I use checklists and templates to keep me from forgetting or overlooking something.
Some of this documentation might be selected to be kept up to date, but the majority of it will just be archived or deleted. The value isn't in the documentation (the artifact); it's in the process of thinking through the problem and shaping it into a medium that can be reviewed and shared. The value is in developing the programmer's or tester's understanding about the problem being solved.