Documentation – What does it mean?

“Working Software over comprehensive documentation” The Agile Manifesto

Lately my team has struggled with the agile principle of minimal documentation. They have adopted the attitude, see the sense of it, and have gleefully thrown off the expectation that they should be doing any documentation that does not contribute to working software.

But we need it…

As we’ve progressed through the project, however, its been clear that sometimes documentation is a useful lubricant between scrum teams.  The contradiction boggles them as new agile practitioners and they struggle with the fine line of what and when to document and what to let go.

My business analysts find their spreadsheets threatened and their sense making documents under scrutiny, by themselves.  My developers find themselves struggling with the formality of a User Story when all they want is a ‘story’ level piece of work telling them to setup a new environment.  My SQA’s wonder how they are supposed to do Anything without a document to follow.  This struggle for discernment was a good thing.  It opened the conversation on what was valuable and sustainable and what helped us deliver working and relevant software the most frequently.

I spent two sprints trying to get my hands around the root of the issue.  I finally found an outline to help explain the agile principle in the context of our team, our project, and the challenges we faced.

Our project – our circumstances

  1. New to agile and tools like continuous integration, automated testing, behavior driven development.
  2. A mixed consultant and client team
  3. Manual testing
  4. Manual compliance and regulatory oversight
  5. New technology stack
  6. New content management system
  7. New outsourced infrastructure management
  8. No consistent practice of architecture documentation or a system map
  9. SDLC documented but new and not always adhered to.

As you can tell we were starting from scratch with almost every aspect of agile development and software quality principles.  We just had agile principles and a willing and enthusiastic team. This situation is not unusual in a company adopting agile practices.  Like most areas of uncertainty we simply discussed it as a team and came to common ground.  Here are the definitions I now work from as my team’s Scrum Master:

Definition of Documentation – for our project

  1. Documentation is a Persistent artifact that will be maintained over the life of the product.  Resources will be dedicated to keep it up to date.  It will be valuable because it is used to maintain quality and track the user directed change to our software.
  2. Requirements Documentation is necessary to our SDLC as it provides a set of expectations for our SQA’s to test our product against.
    • We will use formal User Stories as requirements documentation and store them in our quality software.
    • The ‘back side’ of the User Story will contain the test scripts written by our SQA’s against the acceptance criteria we used to develop on.
    • As features evolve their User Stories and test scripts will be modified to reflect the iteration.  This gives us a complete and accurate set of requirements in our quality software.
  3. Technical Documentation will not be written in a static format. We will document in the code.  The code will conform to our coding standards which will reside with our Architecture/System documentation.  Developers should see our standards in our code.
  4. Architecture/System/Design Documentation will be minimal and kept in our team wiki.  It will be maintained by the Development Team Lead and Lead front end designer.  Areas of particular risk for security, transmission of PI, and compliance will recorded in language that is easy for an auditor to understand.
  5. User Documentation will be part of the site in the form of Help and FAQ’s.  Internal users will have user documentation developed for the CMS under a separate scope.

Work product is not documentation 

Spreadsheets to keep data paths straight, gather user input and write down changing requirements are work product, not documentation.  We don’t intend for them to live beyond the project.  Our team can use whatever they find most efficient to communicate information as long as it is understood that the static documents are not Documentation.  We need to produce a spreadsheet with all the possible data variants that could appear onscreen depending on the user profile logging in.  Our developers need those permutations gathered.  Is it documentation? No. Its certainly a helpful work product.

Other opinions

This set of definitions works for my current project and team.  There are many other opinions on the matter that may suit your project, team, and development tool set.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s