insight
Insights
By: Sagar Sharma

All you need to know about the infamous D word of Software

People usually misinterpret one of the Agile Manifesto’s declarations “Working Software over Comprehensive Documentation”. Documentation is not a profanity in Agile; all the manifesto says is to restrict it to a bare minimum and not let it become an impediment. The question arises, how to gather and document software requirements in Agile Software Development environment.

How to Document?

It is not rare for teams new to Agile to attempt moving their existing requirements into User Story format. This can create a backlog of thousands of user stories, followed by a lengthy prioritization cycle. At the end of the day, converting the software requirements gathered for a waterfall process to user stories meant for Agile is simply a waste of time; both vary a lot in their intent and scope.

Here’s how User Stories completely differ from traditional Software Requirement Specification (SRS) documents:

User StoryTraditional SRS Documents
Slim: Developed just-in-timeHeavy: Their equivalent Use Cases are much more elaborate
Accurate: During backlog grooming, User Stories are refined with developers’ feedbackInaccurate: Devoid of developers’ feedback, a lot of guesswork is involved in the documentation
Simple, fast and cheap Complex, slow and expensive
Rarely out of dateMostly out of date: Specifications developed today rarely capture the requirements and discoveries six months down the line

A user story is a very high-level definition of a requirement from a user point of view, containing minimum viable information for developers to estimate their effort and plan accordingly.

Standard User Story Format

As a <type of user>, I want <some goal> so that <some benefit>.

Example: As a registered user, I want to login so that I can access my account.

User stories are incomplete without their Acceptance Criteria (AC). AC are critical documentation bits which help developers in a team to write accurate test cases without any ambiguity and understand business values better. Although, the Product Owner writes AC, Quality Analysts and Developers also contribute to improving the AC. AC ensure that all the parameters of a User Story are met as per every stakeholders’ agreement. Only when the AC are “Accepted” the user story is marked as “Done”.

Standard Acceptance Criteria Format (derived from Gherkin)

Given <precondition(s)> When <some action> Then <a result/set of results>

Example: Given the user hasn’t ordered yet, when the user adds any apparel into the shopping cart, then apply a discount of 20% to the total

"According to me, Agile development teams are only concerned with user stories and acceptance criteria. That's all the documentation they need. For them, deployment and maintenance manuals are all Greek. We have separate guys for creating those manuals"

Jainam Shah Project Manager, Credencys

What to Document?

Each project has its own requirements, and your domain expertise will let you know what areas require major documentation. While this may logically tempt you to create repeatable templates; it’s not recommended. By keeping close coordination with the end users, you can identify the format and quantum of information they would like you to deliver. For instance, there could be two major document types; the one fed to the product backlog and used by developers and the one which is created at the end of sprint (to be read by client/support teams). Scrum facilitates this close coordination between developers and end users on a more frequent basis which means that documentation can be restricted to a high-level overview. This approach minimizes waste during all stages of documentations viz. discovery, design, development, QA, release and even post release/support cycles.

Where to Document?

This is quite obvious; you will want to keep all your documentation with proper backup and access to all stakeholders. This ensures that everyone is on the same page and there are fewer chances of overlaps or lapses. At the end of every Sprint, you might feel the need to compile all feature implementations, feature improvements, and bug fixes, in the form of a report which is usually referred as Release Notes. As the project progresses, you might consider developing a Wiki page with an index linking to all your documentations in some order.

When to Document?

As Agile is an iterative and incremental process, documentation would continue throughout the project. The best way to document is to do it in gradual phases, not investing too much of time so that feedback from concerned parties takes it into the right direction. Something written in one go, can be rejected in one go. Further, during sprints, it’s recommended to have only that much documentation ready in advance which is enough to fill the product backlog so that development team doesn’t have to wait. You can determine this by taking into account the Sprint duration. The goal of documentation in such time-boxed delivery cycles is to allow product owners provide clarity on what needs to be built with what priority.

Credencys Solutions Inc is a leading software development services and solutions provider which has helped numerous businesses in building strategies for their business growth. Subscribe to our blogs for getting similar articles on management, strategy, leadership and more.

icon-logo

AGILE APPROACH.
EFFICIENT TEAM.
DELIVERING WOW.