Lightweight Documentation… Not Lightweight Thinking

This content is syndicated from LeadingAgile by Mike Cottmeyer. To view the original post in full, click here.

Working software over comprehensive documentation… this line in the manifesto has been used to justify all manner of undisciplined thinking over the years. Just because we value working software over comprehensive documentation, doesn’t mean we don’t ever write anything down… and it especially doesn’t mean that we don’t think through problems. It doesn’t mean that we don’t do the discovery, analysis, and design that often was captured in all that comprehensive documentation. The problem with comprehensive documentation is that it is a poor communication tool for helping developers understand the needs of the customer. It’s a poor communication tool for explaining to a team of developers how to build a product. It’s a poor predictor of what the product will even do when it is done. Documentation is essentially a transient artifact, intended to keep a record of decisions and communicate intent.  Far too often it’s used as a primary measure of progress… especially in the absence of incremental delivery of working software. In more traditional environments, people are tasked to create some sort of a requirements document, or maybe a design document or a project charter. Somewhere along the way, many folks start to think that the mere presence of the artifact is all that’s required to build software. The document becomes an end unto itself. It’s not the document that’s important… it’s the shared understanding that came out of creating the document that’s important. The document is simply an artifact representing that shared understanding. Six or seven years ago I was mentoring a junior Project Manager that was struggling to create a project charter. I sat down with him and started asking him who he had met with, what was his understanding of the goals and objectives of the project, and what he knew about the assumptions, risks, budget, and expectations surrounding the project. His response? I haven’t met with anyone… my job is to write this charter. He somehow had come to the conclusion that the mere presence of a charter was the end goal. Yes, his job was to write the charter… but ONLY after he facilitated the discussion that generated the shared understanding that was to be written in that charter. Many folks new to agile feel like they no longer have permission to write stuff down. I encourage them to write down whatever they need to write down, but not to think of the document as the deliverable, think of the document as a record of an agreement that we want to track. Maybe a tool for thinking through a problem.  If you want to use a template or a form to help yourself think through all the things you may want to consider while decomposing the problem… that’s fine. Use documentation as a record of what has been created, rather than a prediction of what should be created. At the end of the day, documentation does not reduce risk or validate assumptions, and no amount of documentation is a measure of progress on our project. But just because we do lightweight documentation doesn’t mean lightweight thinking… we just want to do the simplest thing necessary to facilitate shared understanding of the emerging product we are trying to build. Shared understanding of the problem, and agreement on how to proceed, is what we are going for. Documentation is never a goal unto itself. That is why we value working software over comprehensive documentation.

Leave a Reply

What is 5 + 5 ?
Please leave these two fields as-is:
Please do this simple sum so I know you are human:)

There are 101 ways to approach anything.
To find the best way, sometimes you need expert help

What People Say

“Kelly revolutionised the way our digital department operated. A true advocate of agile principles, he quickly improved internal communication within our teams and our internal clients by aligning our business and creating a much enhanced sense of transparency in the decisions the business was making. Kelly also introduced a higher sense of empowerment to the development teams...”


“Kelly’s a leading program director with the ability to take charge from day one and keep strong momentum at both a program and project level driving prioritisation, resourcing and budgeting agendas. Kelly operates with an easy-going style and possesses a strong facilitation skill set. From my 5 months experience working with Kelly, I would recommend Kelly to program manage large scale, complex, cross company change programs both from a business and IT perspective.”


“Kelly is an extremely talented and visionary leader. As such he manages to inspire all around him to achieve their best. He is passionate about agile and has a wealth of experience to bring to bear in this area. If you're 'lucky' he might even tell you all about his agile blog. Above all this, Kelly is great fun to work with. He is always relaxed and never gets stressed - and trust me, he had plenty of opportunity here! If you get the chance to work with Kelly, don't pass it up.”


“Kelly is an Agile heavy-weight. He came in to assess my multi-million $ Agile development program which wasn’t delivering the right throughput. He interviewed most of the team and made some key recommendations that, when implemented, showed immediate results. I couldn’t ask for more than that except he’s a really nice guy as well.”


“Kelly and I worked together on a very large project trying to secure a new Insurer client. Kelly had fantastic commercial awareness as well as his technical expertise. Without him I would never had secured this client so I owe a lot to him. He is also a really great guy!”


“Kelly came to the department and has really made a huge impact on how the department communicates, collaborates and generally gets things done. We were already developing in an agile way, but Kelly has brought us even more into alignment with agile and scrum best practices, being eager to share information and willing to work with us to change our processes rather than dictate how things must be done. He is highly knowledgable about agile development (as his active blog proves) but his blog won't show what a friendly and knowledgeable guy he is. I highly recommend Kelly to anyone looking for a CTO or a seminar on agile/scrum practices - you won't be disappointed!”


“Kelly was a great colleague to work with - highly competent, trustworthy and generally a nice bloke.”


“Kelly was engaged as a Program Director on a complex business and technology transformation program for Suncorp Commercial Insurance. Kelly drew on his key capabilities and depth of experience to bring together disparate parties in a harmonised way, ensuring the initiate and concept phases of the program were understood and well formulated. Excellent outcome in a very short time frame. ”


“I worked with Kelly on many projects at IPC and I was always impressed with his approach to all of them, always ensuring the most commercially viable route was taken. He is great at managing relationships and it was always a pleasure working with him.”


“I worked with Kelly whilst at Thoughtworks and found him to be a most inspiring individual, his common-sense approach coupled with a deep understanding of Agile and business makes him an invaluable asset to any organisation. I can't recommend Kelly enough.”


“Kelly was a brilliant CTO and a great support to me in the time we worked together. I owe Kelly a great deal in terms of direction and how to get things done under sometimes difficult circumstances. Thanks Kelly.”