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

综合技术 2018-12-07 阅读原文

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

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

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.

责编内容by:Gurock Software Blog 【阅读原文】。感谢您的支持!


Avoiding The Adjective Fallacy You’re reading this, so I’ll assume your English is pretty good. What’s wrong with these phrases? Old little lady ...
What’s Next After PMI-ACP Certification and What’s... What’s next after PMI-ACP certification? Over the past few years I’ve been progressively developing a new approach for P...
SSRF (Server Side Request Forgery) testing resourc... SSRF (Server Side Request Forgery) testing resources Quick URL based bypasses:
MAAS Development Summary – July 30th 2017 Hello MAASters! The MAAS development summaries are back! Over the past 3 weeks, the team has made good progress on ...
Upcoming hotness from RelEng To kick off the new year, I'd like to share some of the exciting projects we have underway in Release Engineering. ...