Will Anyone Read an Article About Documentation?
I am pleased with the response to the articles I have published on LinkedIn, but a total lack of interest in one article surprised me. The rhetorical question How can agile teams produce comprehensive documentation? seemed like a great title to me because it was echoing one of the values in the Manifesto for Agile Software Development:
working software over comprehensive documentation
I had also planned it as the second article in a theme that I started with How Can Agile Teams Capture Non-Functional Requirements?
On reflection, I probably shouldn't be too surprised at the lack of interest. Including the word documentation in the title of an article almost guarantees that no will read it! Or maybe it's because my reference to comprehensive documentation is too subtle? I was relying on the final statement of the manifesto to provide the context:
that is, while there is value in the items on the right, we value the items on the left more
In other words, I understand the manifesto to be saying:
there is value in documentation but working software always has greater value.
Echoing the title, the article starts with three more rhetorical questions:
- What happens to a Sprint Backlog Item at the end of a sprint?
- Does it have no further use?
- Should the team just tear up the story card and throw it away?"
I then go on to propose that teams should create a Product Inventory containing completed sprint backlog items that will serve as a growing repository of comprehensive documentation for very little additional effort on the part of the team.
With this in mind, I have renamed the article to What happens to sprint backlog items at the end of a sprint?
I help organisations improve the way they define and deliver software.
6 年Hi Rebecca, Politics! Writing so much easier than the real world :) First off, one of the points of my post was that because of its awkward wording, many people misread the Agile Manifesto.? What it actually says is "we value documentation but we value working software more".? Your approach of documenting the 'as-built' use cases in Atlassian is exactly what I had in mind when I described the Product Inventory, except doing it all after the software has been released is not ideal. The philosophy is to reuse as much as possible and supplement it with minimal documentation generated during the sprint.? The mindset should be "if I spend a minute to document this now it will save me (or someone else) a lot of time creating some working software the next time this comes up".?? Anything I can do to improve team velocity is worthwhile and adds value. Not sure why user stories in Jira would be thrown away.? If they are good stories they should have acceptance tests defined which can provide really useful documentation.? I wonder if this might help https://en.sparxsystems.es/plugins/eaconnectorforjira/ It would allow you to capture and structure the user stories in EA without the need to re-write everything. Let me know how you go.
Applications Development Manager at Department of Transport WA
6 年Hi Phil, Thank you very much for your informative blog posts. I was hoping you can give me some guidance in what to do in terms of product specifications for an agile environment. We have multiple products in our workplace, that are all in production and that have several project teams and even support teams working on them all at the same time. Each project has different scrum teams, requirements, product owners (as the products are used by many different business areas) etc... What I have found is that we are getting tripped up on our documentation. Different teams work in different ways and it is making it difficult to have a living "product specification" or even a Product Inventory.? We are finding that when projects that have their requirements as part of their user stories (stored in JIRA), they become throw-away and it is not possible to trawl through all of the many JIRAs across projects to understand what the system is currently doing. Our systems are highly complex, so just looking at the code is not easy to do in a timely and accurate fashion. We have dabbled with use cases being documented in Atlassian confluence, with the user stories referring to certain points of the usecase. The usecase is then a living document and is baselined and archived per release. This seems to have worked best to have some type of a product specification, as all projects that may touch certain areas of a product have a usecase to refer to and edit accordingly. However, then there are people who say this is too onerous and is against the agile manifesto of working software over comprehensive documentation. I personally am struggling to find a happy-medium. Any advice? Thanks very much