Striking a Balance of ‘Just Enough’ Documentation in an Agile Project

Documentation in an Agile Project, Just Enough Documentation, Agile Testing, Agile Requirements, Value, Communication, Sufficiency. TestRail

This is a guest posting by Nishi Grover Garg.

Agile poses many challenges to the development team, most of them pertaining to time. Teams are perpetually under pressure to deliver working software at a fast pace, leaving minimum time for anything else.

The Agile Manifesto emphasizes working software over comprehensive documentation, but most agile teams interpret this wrong and treat documentation as something to be avoided, owing to time constraints. The manifesto states a lesser focus on comprehensive documentation, but some documentation is still needed for the project and any related guidelines being followed. Attaining this balance is a challenge.

Documentation is a necessary evil. We may think of it as cumbersome and time-consuming, but the project cannot survive without it. For this reason, we need to find ways to do just enough documentation — no more, no less.

Any types of documents created during the software development process that are not consumer-facing are a part of internal documentation of the project, and that is where we need to create a balance. Focus must be on documenting just the right amount to be able to successfully deliver, manage and maintain the project, keeping all stakeholders sufficiently informed but not going overboard.

Get TestRail FREE for 30 days!


Where to Direct Focus: Value, Communication, Sufficiency

Documentation in an Agile Project, Just Enough Documentation, Agile Testing, Agile Requirements, Value, Communication, Sufficiency. TestRail

The first thing to focus on must be value. We must make any activity we do value-driven. Anything that does not provide value in return must be disregarded. Base your decisions on one of the 12 Agile Principles: “Simplicity — the art of maximizing the amount of work not done — is essential.” Simplify wherever possible, and reduce unneeded processes and documents.

The next thing to focus on should be communication. Most written communication, such as email conversations and long chains of messages, can be replaced with a good discussion among team members. This entails having good communication channels with open access, and encouraging the team to talk it out. Later, the outcome of the discussions can then be documented and shared for others’ reference on a common portal. This way, we reduce documenting stuff that is wrong or doubtful, and we avoid wasting time on reviews and chains of communication to extract the correct information.

The final area to focus on should be sufficiency. This is what we mean when we say “just enough.” The goal is to document what is needed, in no more detail than is necessary. Any document you are creating, be it requirements, user stories, designs, test cases or plans, should have just enough details to communicate the needed information and reduce all wasteful components.

For example, in a traditional test design document, we create columns for test case description, test steps, test data, expected results and actual results, along with preconditions and post-conditions for each test case. There may be a very detailed description of test steps, and varying test data may also be repeatedly documented. While this is needed in many contexts, agile testers may not have the time or the need to specify their tests in this much detail.

Receive Popular Monthly Testing & QA Articles

Join 34,000 subscribers and receive carefully researched and popular article on software testing and QA. Top resources on becoming a better tester, learning new tools and building a team.

We will never share your email. 1-click unsubscribes.

Agile Testing, Agile Requirements

Documentation in an Agile Project, Just Enough Documentation, Agile Testing, Agile Requirements, Value, Communication, Sufficiency. TestRail

As an agile tester, I have worked on teams following a much leaner approach to sprint-level tests. We document the tests as high-level scenarios, with a one line description of the test and a column for details like any specific test data or the expected outcome. When executing these tests, the tester may add relevant information for future regression cycles, as well as document test results and any defects.

These types of tests are very quick to specify, with most time being spent on designing and thinking rather than writing them. We also have the flexibility to frequently edit the tests when things change. And because agile teams are small and most members know each other’s modules, it’s easy to understand and test from these basic instructions, even when one of us is not the author for the exact test cases we’re executing. We then upload these tests to our test management portal, which automatically maps the data columns into meaningful sections.

This makes sense for a team like ours, but even if you had to have more detailed test cases, it is possible to translate these types of tests into a more detailed test case if needed, once they have been executed and the feature is stable enough.

The same applies to agile requirements. In traditional requirements, we may have more details and highly worded explanations for each feature. But in agile, we can use devices like user stories, where we can explain the basic feature in a simple format and then follow it up with a discussion about the feature, which results in distilling the information and finding out a list of acceptance test criteria. This discussion is much more fruitful than having a detailed requirement document because it brings out finer points and varied perspectives, and the resulting list of points acts as a basis for developers and testers for their next efforts.

We may also make use of some visualization tools, like mockups for requirements and designs, mind maps for project plans and test case designing, and innovation games for better collaboration and brainstorming ideas.

Documentation is an important tool when it’s created appropriately and with enough detail — but not too much. Finding better ways to make our documentation practices more valuable and lean will help us achieve success in our agile endeavors.

Nishi is a consulting Testing and Agile trainer with hands-on experience in all stages of software testing life cycle since 2008. She works with Agile Testing Alliance(ATA) to conduct various courses, trainings and organising testing community events and meetups, and also has been a speaker at numerous testing events and conferences. Check out her blog where she writes about the latest topics in Agile and Testing domains.

Test Automation – Anywhere, Anytime

Try Ranorex for free

How useful was this post?

Click on a star to rate it!

Stay ahead in Test Management.

Follow us on social media!

Help us improve this page!

What problem are you trying to solve?

In This Article:

There are no headings in this document.

Sign up for our newsletter

Other Blogs

Agile, Integrations, Jira

How Software Development Company ELEKS Increased Visibility and Productivity by Integrating Jira with TestRail

Read more about how the QA team at ELEKS evaluated different test management solutions and why they ultimately chose TestRail.

Agile, Integrations, Jira

How to Report on Traceability and Test Coverage in Jira

This post covers how to show test coverage, manage requirements traceability, and create a traceability report in Jira.

Agile, Integrations, Jira

Jira for Test Management: Options, Challenges, and Solutions

Learn about the pros/cons of using Jira as a test management solution, alternatives, & how teams that use Jira manage their testing. 

Build quality processes and release with confidence