The second point of the Agile Manifesto states, “We value working software over comprehensive documentation. That is, while there is value in the items on the right, we value the items on the left more.”

Programmers have flocked to the Agile Management style because, in one popular view, it frees them from the tedious exercise of documentation. But that is not at all what Agile teaches. In fact, this viewpoint violates the Agile Manifesto statement.

Projects are guaranteed to encounter the following issues when documentation is ignored:

• “You gave me what I wanted, but not what I needed!”
• Late delivery or incomplete software solution.
• Poor performance or unreliable software solution.

“You gave me what I wanted, but not what I needed!”

How often have projects been completed following every request the customer asked for and then the customer doesn’t use the software or is disappointed with the results? Whenever this happens it is solely because of a lack of understanding about the problem that could only be avoided with proper documentation. It doesn’t matter how well a project is executed if you’re doing the wrong thing!

Late delivery or incomplete software solution

Whenever a product is delivered late or incomplete it generally indicates that the design was not thought-out enough. This may occur for a couple of reasons:

1. The SCRUM Master failed to plan cleanup iterations throughout the project to give developer’s opportunity to identify refactoring opportunities to resolve poor designs or adapt software based on updated knowledge, and/or
2. There was inadequate time spent on documentation ensuring that the development staff invested adequate effort into the design to ensure a successful outcome.

As the project chugs along the software because more difficult to adapt to changing business needs causing one or more of the following issues: instability, inefficiency, or inability to meet business needs altogether.

Poor performance or unreliable software solution

This scenario occurs when the non-functional requirements aren’t taken into consideration. The problem with avoiding documentation is that nobody is able to remember everything that must be considered for a project’s success. Without proper documentation the information is never requested, lost or forgotten.

Reasons to Create a Document

How do we reconcile the cost of creating and maintaining documents with the higher priority of creating working software? Documentation for documentation’s sake was (and for many companies continues to be) a huge waste of resources causing frustration and disappointment among project team members.

Valuing working software more than documentation means that we value meaningful documentation at the correct moment. Too much documentation too early and the project suffers. Likewise, not enough documentation too late and the project suffers. Common sense must prevail when it comes to documentation. We can’t give ourselves permission to use the Agile Manifesto as an excuse to avoid necessary and valuable work.

In this section we will review the reasons that justify the need for documentation.

Documentation is Communication

Documentation is a form of written communication. Documentation provides a traceable, verifiable means to ensure that the spoken communication successfully conveyed the correct meaning to the receiver.

It is for this reason a business analyst will traverse thru the following set of steps for every project feature or change request:

• Elicit from the stakeholder the requirements surrounding the feature.
• Document the feature and related requirements.
• Review the documented requirements with the customer.
• Update the documentation based upon the stakeholder’s clarification.
• Compare the verified requirements with existing requirements for conflicts or negative outcomes.
• Pass the requirements off to the development staff.

In this context documentation makes work items verifiable, auditable and reliably transmittable. The primary point is that we shouldn’t view writing as documentation. Instead we should view it as reliable communication.

Elicit New Perspective

Documentation is a tool that enables you to see a problem from another perspective. Entity relationship diagrams, sequence diagrams, class diagrams, activity diagrams, and other modeling tools represent a form of documentation. These tools help developers identify design errors early in the project when it is easiest (and cheapest) to make corrections.

Provide Historical Context

Design tools assist new developers by providing answers to the question, “What the ____ were they thinking?” Without an organized set of features, supporting requirements and designs, it is very, VERY (did I say very?) difficult for new developers to support the system as intended resulting in violation of the original design making the software product inflexible, fragile and ultimately unreliable.

Improve a Process

Think retrospective. At the end of each sprint a retrospective meeting is held where the results of the last iteration are documented and shared with the team members. This information is then used to alter the next iteration making it more stable, efficient and effective.

Pilots use a checklist to verify that they do not skip an important step in the pre-flight checklist. Failure to properly execute each step may result in deadly consequences.

Documentation acts as a means to demonstrate that quality work has been completed. Often, the mere act of completing a template for a process ensures that the documenter provided adequate consideration of all key points that can affect the process.

When to Document

• When it is important for everyone “to be on the same page”.
  Note that in this context it is even more important to keep your statements concise, clear, verifiable and truthful.
• When statements need to be auditable.
  You need to know who made a decision and why the decision was made.
• When statements need to be traceable.
  The requirement can be followed to the lines of code supporting it. The lines of code can be traced back to the original change request and requestor.
• When ideas need to be shared, reviewed and verified.
• When relationships between ideas need to be understood.
• When context is important.
  Having a list of user stories is good. Having a list of user stories in context with themes, epics and features is excellent!
• In response to company or government regulations.
• To manage and control risks in a process.
  • Ensure that important topics are covered in a meeting.
  • Demonstrate quality invested in a task.
• As training with the intent to reduce the cost and time to bring new resources up to speed on a project or activity.
• For clarification to ensure a concept is understood.
  Don’t document what you coded, document why you coded it the way you did!

Documentation Forms

Documentation comes in many forms. Information may be documented in a document, list, spreadsheet, diagram, email, text message, inline comment or other medium. Whatever form the documentation takes it must be appropriate for the intended audience providing value both in how it is stored and the content served.

An Agile Document

A document may be considered agile when it adheres to the following criteria:

• The benefits of creating and maintaining the document outweighs the costs.
• Stakeholders understand the total cost of ownership and value the end result.
• The document is lean and sufficient.
• The document is necessary fulfilling a purpose.
• The document captures critical information.
• The document is created for a specific customer making their job easier.
• The document is sufficiently complete, accurate, consistent, unambiguous, verifiable and traceable.

References

• Manifesto for Agile Software Development
• Why Agile Documentation Makes Sense for WordPress
• Strategies for Agile Software Development
• Karl Weigers, Gathering Software Requirements, Second Edition