Friday, March 21, 2014

Agile Documentation

And this, class, is what we call BLASPHEMIES!!!
One of the most common myths I get to dispel as an Agile Coach is that Agile teams don't document. After all, they value Working Software, not Comprehensive Documentation. I have to remind them that the Manifesto states "over" instead of "not", and that true Agilists still see the value in documentation inasmuch as it enhances the working software being developed. These conversations have helped me refine my message over time to the four questions I believe should be asked before documentation is produced.

Who are you documenting for?
Set permissions to 'write-only'
Who is going to read this document that you're going to write? Dean Leffingwell once told me that Agile means avoiding "write-only" documentation. If it's not going to be read, why write it?

Understanding your audience also impacts how you write your documentation. Speak to the level and with the verbiage which which your consumer is most comfortable. This is similar logic to why we include the user in the standard User Story format.

How will you communicate your documentation?
Documentation is not one-size-fits-all. There are hundreds of ways to document, from wikis to man files to interactive wizards. What format are you going to use to publish your documentation?

Another interpretation of this is where will you put the documentation for your consumers to pull? Most documentation is living, not static, so mediums like email are usually very bad. Do you have a team site, knowledge repository, or some other digital location that your consumers can bookmark to find the latest and greatest? Is the location easy to find and "on the main path", or do they have to dig for it? Make your life easy by making your documentation easy to consume.

What will be done with your documentation?
This is more a corollary for the first two questions. For example, you may think you know who you're documenting for, but what if all they do is file the information away and never look at it? Your audience may not be who you think it is - indeed, your audience may not exist at all.

As for the second question, building a README file to document your smartphone game won't be useful, regardless of how well you know your customer or how accessible you make said file - an in-game tutorial will be much better received.

Bottom line: don't start documenting until you know what your consumers' intended purpose is for the documentation.

Can it be automated?
The first three questions speak more to the elimination or simplification of the documentation you produce. By the time you get to this question, you've determined that the documentation is necessary for your end-user, future maintenance team, or whomever to do what they need with your software. So can this documentation be automated?

Documentation for future development and maintenance is often quite simple to automate. You can use certain comment formatting to generate Javadoc or Sandcastle documentation for Java and .NET applications, respectively. You can use tools to generate your class and sequence diagrams as part of each build. There are several forms of technical documentation that can almost always be automated.

User-facing automation is trickier, but not impossible. For instance, you could generate LaTeX templates that are plugged in with data that's auto-fed to it and output documentation in the format that works best for your users. Get creative with it and see what you can come up with.

Questions?
Those are the questions I've developed over time; what are yours? How do you determine what to document and how? Do you find yourself documenting more or less using Agile than Waterfall? How has the nature of documentation changed? I'd love to learn from your experiences.

No comments: