Documenting for Success

Creating product documentation for Agile teams

Building a great product that is unique and exceeds the expectations of customers requires thorough research and planning. To achieve this — and do it on time — a product team needs to clearly define product requirements through documentation. Only after requirements are defined can timelines can be set accordingly.

Let’s have a look this idea through the eyes of business teams. At Kite, we believe that the user-centered choice and the business-savvy choice are one and the same. We think first about what the end user needs, since an enhanced user experience is both a product differentiator and a driver for business-sustaining innovation. While many business analysts may know and understand this concept, it’s an altogether different experience to map it out and execute.

We know how important user stories are for building awesome products. Each one illustrates the experience our customers will have while using our product. At Kite, we have combined stories with functional requirements in a single document. It is the most powerful tool in our belt, and works as a bible for our designers and tech team. We follow Agile methodology, which means our work depends upon a shared understanding between the business, product, design and engineering teams. Discussing product features with these different teams at Kite helps us receive feedback and shape product features, letting us offer the best customer experience in the end. Based on feedback and shared understanding, we then start creating user stories. User stories feature mainly high-level specifications, since more granular implementation details are left to the engineering team to sort out.

Establishing a shared understanding between teams

1. At Kite, we have design, engineering and business teams conduct research. This includes things like competitor analysis as well as customer interviews, which help everyone better understand what the end user’s pain points are.
2. Communication is essential. As a business analyst, I have to not only clearly communicate product specifications but also be an educator. It is important to show the vision for the product so that the engineering and design teams clearly understand their roles and perform tasks more efficiently. They, in turn, can be more innovative and suggest better ideas too.
3. Measuring our goals has helped set expectations for delivery. Creating realistic timelines for product delivery is critical to communicate both internally and to our customers.
4. Prioritizing features has also contributed to better inter-team communication. These debates help create consensus-based strategies for upcoming sprints. Of course, this can be difficult to accomplish when there are many features to be rolled out, and limited resources; prioritization often involves letting go of certain features for the sake of long-term success.

Keeping user stories lean and precise

It’s not enough to just have a shared understanding between teams. It is equally important to keep requirements lean as much as possible so that you can execute quickly. This involves using a consistent format for user stories so that feedback and brainstorming can happen effectively.

1. User story objectives
   Keep it simple. The user story document should clearly explain the description of a feature in a few lines so that it is easier for everyone to understand.
2. Use case description
   This explains the use case in detail. It clearly describes the actor’s characteristics and the flow of events from the actor’s perspective. It should also contain pre- and post-conditions, trigger business rules and any assumptions taken.
3. User interaction and wireframing
   We know a picture speaks 1000 words. We believe that engineering and design teams better understand the flow of events through wireframes. We use Lucidchart, which helps us combine our use case diagrams and wireframes on a single platform. We then create technical specifications based on the parameters shown in wireframes.
4. Validations
   This is useful for both UI developers and the back-end development team to clearly set validations for their parameters.
5. Communication scenarios
   Most products rely upon communication — SMS, email or push notifications — for their success. We mention actors and text variables for all communication scenarios. We then create technical specifications based on these parameters.
6. Analytics
   We believe data is lifeline of the product, so we define various scenarios to capture user behavior and data points for customer segmentation and funnels. Data collected is then used in analytics tools, helping everyone make more accurate, data-based decisions.

Challenges and solutions

With every approach, there can be downsides as well. Here are two challenges that I have experienced and observed:

1. Lack of participation
   How do we encourage people to actively comment and contribute? In a lot of ways, it comes down to the culture within the organization. At Kite, we have a team that openly gives comments on user stories. To develop this culture, I spoke with key stakeholders and leaders in the company to understand the problems they faced. I surveyed different engineering teams to identify gaps in the development process. After understanding the needs of Kite’s teams, we established a system in which teams review documentation and share feedback before the sprint starts.
2. Documentation can go sour
   Since requirements evolve based on feedback and newer technologies, it is always good practice to keep documents updated with newer versions, while keeping track of older versions as well. It is worth questioning whether some changes require updating documentation or not, and is worth discussing with your team.

Agile requirements: the way ahead

If you follow Agile methodology, you should remain Agile in your product documents as well. It’s okay to change user stories as the team builds, ships and gets feedback from customers. I recommend using a platform to link user stories to the corresponding tasks of development teams. This may involve shipping fewer features for the sake of maintaining a healthy and transparent engineering culture.