Should Agile Product companies quit documentation?

I don’t believe in textbook Agile — there, I said it, but I am going to offer an alternative interpretation of the Agile Manifesto’s documentation clause for Product Development.

I am a believer in Agile the methodology, but I have not made it a dogma for myself. In my opinion, like everything else, you take Agile then tweak and twist it per your needs and you’ll have your secret recipe after a few attempts.

The Manifesto for Agile Software Development says:

working software over comprehensive documentation

I see a lot of folks confusing this to mean NO documentation. If you are a group of three friends working on a freelance gig — fine; but if you are medium to small sized organisation working on a Product impacting people, you need documentation.

You don’t want to end up in a situation where few years down the road you don’t know what you built and have to hire someone to un-assemble the piping and find out what it is and how it works. A Product organisation unaware of their own product, won’t be too exciting for potential users.

Wile I agree some of the knowledge of Product will always remain in people’s heads but trying to skip documentation is putting yourself at risk. Imagine losing those people and the Product knowledge with them!

Here’s my interpretation of Agile documentation:

What this means for me is that, instead of thinking of documentation as a silo-ed operation where you complete a set of 1000 page documents which none reads and becomes a dependency for development; you should make it part of the process i.e. not waterfally, not blocking, and surely a team support fostering collaboration.

My take on Agile documentation is that we should think about:

  • how much to document — find the right balance
  • where to document — think of a collaboration platform and feedback loop
  • what kind of documents are needed — think consumers, internal and external both short and long term
  • when they should be written, and importantly
  • who should be writing them — IMO, a team!

It doesn’t end there — you should also make a strategy around how to expose that documentation to intended audience. One thing I always do, as an example, is to set aside some time to run people through that important document in a quick meeting to kickstart their interest and ensure we open a feedback loop to collaborate on it.

JIRA is not a Product documentation tool

I can not emphasize this enough — Jira is a ticketing system, a project issue tracker and nothing more than that. Heck, even Atlassian doesn’t think of it as more than that. If this was meant to be a documentation tool to manage requirements or anything else, Atlassian wouldn’t have to build Confluence. Jira should be used by Agile Product teams to track what they are working on and to report on performance, but Product organisations need a platform which keeps a collaborative spirit for the continuous process of documentation. Content in Jira is not enough, and not a replacement for old school documentation done in the right way.

Top tip when you document — use visuals. Human beings have evolved by communicating through visuals. Put that long story into a visual to gain interest, once you have that precious attention, they will read your document to see through all the interesting detail you have put in.

Read my other blog…

Before you go, some things to consider:

  1. Recommend or share this if you found it useful.
  2. Subscribe to Ale Natiq on Medium

blogger, technologist, foodie, vagabond, avid reader, cricket-lover, and an activist focused on human rights and the case for the environment.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store