Every team needs to leave footprints. Anyone who doesn’t document their work in a project, or actively participates in helping create a persistent record of the project, is a Project Asshole.
The whole concept of project documentation seems to generate a lot of angst for many people.
The sins of documentation
This angst can lead or cause people to commit documentation sins. And there are many sins committed in and around project documentation that are totally unnecessary: whether documentation is necessary, when to create it, and when to use documentation.
On whether it is necessary or not, we have two extreme camps: waterfall and Agile. On the so-called “waterfall” methodologies side, we have the sin of full compliance: every document that is mentioned anywhere in the methodology is completed.
At the other end, we have the misguided Agile supporters who claim that “Agile means no documentation”. And I can think of no greater injustice to Agile than this.
During creation, teams produce documentation without thinking. They use templates without concern and fill them with boilerplate text. They then commit the sin of blindly copying and pasting content from one document to the next without consideration. Anyone who doesn’t believe that documents should be specifically crafted for a team/problem/project is a Project Asshole.
Into the development cycle, there are endless sins committed: not fully reading documents; providing late or inappropriate feedback; or having a policy of explicitly ignoring certain types of documentation.
Need is evident
The simple truth is that a project of any kind needs to create and exchange information between its participants in a manner that is structured and relatively controlled.
That means keeping records of its activities, decisions, rationale for making those decisions, and gaps that arise between the expected/committed and the delivered. And the documentation needs to leave a persistent record of its final outputs and outcomes to hand over to whoever uses or maintains the results.
There’s no getting round documentation. The only thing that varies regarding this element is the content and structure. Each project should determine what level of detail is needed, based on inputs from many sources. Internal standards may define some aspects of the constraints, but few environments will not allow tailoring of the recommended structures.
Each project needs just the right amount of documentation for its context, size and scope.“There are just as many notes, Majesty, as are required. Neither more nor less.” — Wolfgang Amadeus Mozart in Amadeus (influential composer of the Classical era)
And the team needs to own everything that is produced in real, practical and useful ways. The most tragic waste of the valuable human resource is producing documentation that is not used or read. And below is an example I remember of such a tragic waste.
The Agile experience
Since the inception of Agile, I have had many circumstances of project teams and members misunderstanding the principles of Agile. From time to time, I will get confident responses stating, “We’re running this as an Agile project, so we don’t do documentation,” which usually led to long and painful discussions about Agile principles.
Some time back, I was asked by my boss to look into some problems involving a couple of projects and the test environment. So I did what anyone would do when taking over a project team, I asked for a scope document, requirements spec or similar documents, so I could get the top-level view of the project. The response was quick and confident: “We’re running this as an Agile project. We don’t do documentation.” As you can imagine, the aftermath was not very pleasant.
The fact that those projects were running into problems primarily due to missed or misunderstood requirements was something that the people were not prepared to acknowledge.
Such statements and thinking about documentation are not only naive but also demonstrate a lack of understanding on Agile practices and project management in general.
In the Agile Manifesto, it doesn’t actually say “no documentation”. It SAYS “working software over comprehensive documentation”.
The waterfall experience
Not so long ago, I overheard an ongoing strained series of exchanges between one of my peers and his “supplier’s” project management counterpart from our internal IT department. The IT project manager had a remarkable ability to avoid my colleague’s attempts to extract the most basic of information: plans, status and estimates.
Then when my colleague was on leave, a junior project manager tried his luck with the IT project manager.
As expected, he had no luck getting the required details. After being pressed repeatedly, the IT project manager exclaimed loudly and with no hint of irony, “Bloody hell! If I’d known you wanted such accurate estimates, I would have read the fucking specifications!”
Remember one of the mentioned documentation sins: not reading documents that are kept and updated.
Documentation is good and needed
I’m not saying that I endorse thick, process driven, template derived documents full of boilerplate content, either from a template or copy & paste from prior documents.
In fact, my one wish is to disable the Control-C and Control-V shortcuts from the moment a project kick-offs till the end of the project.
I once did an audit on a number of test strategy and plan documents from the projects of different teams in my group. My findings (as I expected) were that little of the thinking and writing were specific to each project. Approximately 95% of the content was identical from one document to the next.
Of course there is the argument that common processes and procedures should be applied in similar test and application environments, but this could be referenced in a standards document. But there is a need to answer questions like, “Where was the project-specific analysis on what was specifically required for each project?”
In the end, we must consider if the main success factor for project success is a shared vision, how can this be communicated consistently over time if it isn’t persevered in some written form? How can you maintain alignment and flush out dissonance without something clearly written down for all before and after to follow and understand?
The difference between the right word and the almost right word is the difference between lightning and a lightning bug. – Mark Twain (American author and writer of Adventures of Huckleberry Finn)
Team Charter Clause #6: I will leave footprints
Clause #6 plays an important role in the project team Charter by minimising chances for people to be Project Assholes in regards to documentation.
I will ensure that the team creates a persistent record of the project outcomes and to communicate its status to key stakeholders as required.
I recognise that people may need to review the history of the project while it is still running: to review decisions or validate project progress, status and outlook. I recognise that people may need to review the project because they are looking for ideas on how to repeat the successes or to avoid the failures from my project. I understand that people, teams or organisations may require reports or other information.
I will not debate or argue this necessity. I will work to do this record keeping or required reporting as quickly, accurately and efficiently as possible.
I will be clear, objective, and truthful in the recording of both successes and failures. I will ensure that the effort expended in the project documentation will be reasonable and manageable with respect to the size, scope and complexity of the project. Furthermore, I will neither over-work nor under-work the time required.
I understand that creating a project record is not the responsibility of a single role or individual (e.g. project manager or project administrator) and will participate fully for requests made of me to add to the project record.
What are your thoughts on the objective of this clause? Do you have any suggestions for modifications to the wording?
What do you think your team’s reaction would be to this Charter if you introduced it to your current project(s)?
We’d love to read your comments and thoughts, so please use the area below the article to provide feedback.
If you like this article, perhaps you’d like to be notified when there are more.
Subscribe to the AdamOnProjects Mailing List!
All the Principles