Minimum Viable Documentation – How Much is Enough?

In Agile product management, the execution team’s primary purpose is to ship working software every two weeks. Documentation, whether it be wireframes, process flows, or experience maps, exists to get stakeholders aligned and continue forward movement. At Revelry, this is how we get our stakeholders aligned faster, keep everyone on the same page, and utilize just enough documentation.

The Kickoff Meeting

At the start of a major sprint, we organize a kickoff meeting and invite all stakeholders, including clients, designers, and engineers to review user stories, their business value, and the lists of acceptance criteria.

Here’s an experience map one of our teams collectively sketched out at the start of a sprint for Kickoff, a product we are building in-house to make it easier for agile dev shops to get projects started faster and more painlessly:

experience map

Rough experience map sketched out and communicated in a single morning.

In another world, this deliverable would have been produced in a drawn-out 3-week structured accelerated visioning engagement, with endless client meetings and unproductive back-and-forth. Here at Revelry, we focus on getting to the right idea or feature set first. As a result, the product owner is able to align the design and engineering teams on the sprint’s goals quickly and effectively, leaving more time for actual work to get done.

During the Sprint

No matter how good your requirements gathering sessions are, there are always questions, new ideas, and thoughts that pop up during a sprint. In fact, we encourage an iterative style of software development and maintain a commitment to shipping the best product we can, a philosophy that keeps us flexible and decisive during implementation.

We also do everything possible to make sure there is active involvement not only from the client throughout each sprint, but also internally within the execution team. True to agile, we meet every morning for daily stand ups and keep conversations flowing all day in project-specific Slack channels.

So, what happens when someone gets stuck?

Designers, who are front end developers here, often create basic wires to visualize the user story so that an engineer or designer can get started on work without blocking each other:

product management

Implementation is fluid by staying agnostic on who can start on a particular ticket.

The typical workflow involves an engineer building out basic functionality and passing off a branch to a designer to apply styles, or a designer stubbing out screens for engineers to implement functionality after.

Similarly, engineers often need more details to implement a feature. The following shows a user story that has initial guidance laid out and the real time requirements gathering that followed:

interaction table

An interaction table updating with more information and decisions.

Seeing a gap in the initial acceptance criteria, I took the time to outline specific scenarios and the appropriate interactions we would need to effectively code up this feature, all the while keeping the client up-to-date on our latest thinking.

The best feedback and the ultimate realignment happens when you put an experience in front of users. The more time you have to code, the more complete an experience is, the better the feedback you will get. So, with a commitment to ship the best product, we do everything we can do maintain forward velocity.


Coming from a big upfront design world, I still have great confidence in bringing together smart people to exhaustively think through business goals, process flows, use cases, etc. The issue here, though, especially in today’s world of constant change, is that we can never figure it out all at once. So the intent isn’t to be less comprehensive, but to create just enough documentation to get the job done at the highest standard of quality. We can get 95% there once, but as soon as the brain trust disbands and e-mails take weeks to return, while user research upends the entire product — what then?

Just enough documentation is about committing to getting there 100%, time and time again.

Revelry partners with startups and corporations to deliver digital transformation and innovation.

Let’s work together to create custom software that solves your toughest business challenges.

Visit our Careers page to check for current openings.
Keep in touch by connecting on LinkedIn or follow us on Twitter.

More Posts by Brian Ng: