Shifting left to include technical writers in the discovery process
Have you ever read the documentation for a product and thought, “This didn’t help me. Why did I waste my time?” That kind of frustration makes customers unhappy and leads them to either give up or pick up the phone and call support. So many times, customers can solve a problem themselves by reading the documentation. But, if they feel like they won’t find what they need, they won’t do it.
Producing clear, accurate, and timely documentation should be every company’s goal, but getting there is not as easy as it would seem. You can have the best technical writers in the world, but their skills don’t matter if they aren’t included in the development process and don’t know what features are being created, why they are being created, or when they are being released. Communication between documentation and development is essential, but it doesn’t always happen.
CloudBees is trying to change that. At CloudBees, documentation is considered to be as important as the code. In fact, we follow a “docs as code” model for creating documentation. Technical writers are embedded in the development squads for the products that they support. As a technical writer, I attend all product meetings and sprint ceremonies for my squads. Additionally, I’m included in the discovery process for new features. Being included in the discovery process allows me to write the documentation for a feature before the feature development is completed. By shifting left, documentation no longer lags behind feature releases or holds up releases.
The discovery process
Recently, the CloudBees DevOptics team decided to try a different approach to discovery. The selected approach involves several hours of meetings for five days, with each day assigned to a specific task:
Day 1 - Define the problem
Day 2 - Create rough sketches of ways to solve the problem
Day 3 - Choose one sketch
Day 4 - Create a prototype
Day 5 - Test the prototype
With that process in mind, the discovery team was assembled. The team included front-end and back-end engineers, a UI designer, a product manager, and myself. We all rearranged our calendars to accommodate three- or four-hour blocks of time to dedicate to discovery.
The writer’s role in discovery
What was my role as a technical writer in the discovery process? In the problem definition portion, my role was mostly to listen and observe. The team discussed the problem statement, what success would look like, and what might cause them to fail. Having that background knowledge of the problem helps me to frame the documentation in the right context.
During the problem definition portion, the issue of terminology came up while the team was considering possible risks associated with the new feature. The design that was being conceived represented a new way of thinking about existing functionality. The team marked terminology as an action item. We would need to make sure that we were using terms that were intuitive and that applied to both the existing functionality and the new functionality. Since technical writers own terminology at CloudBees, this action item is one example of the importance of including documentation in discovery.
In the idea-sketching phase, the team broke into pairs to develop rough sketches of ideas for implementing the feature. I paired up with a UI designer, but mostly reviewed and asked questions to help refine the designer’s ideas.
During the decision phase, I had an equal vote on which sketch the team wanted to implement as a prototype.
I was active during the prototype creation by making sure the prototype text was clear and that terminology made sense for the feature. By making sure the text is user-oriented, we can avoid the “engineer-speak” that can be found in many products.
Additionally, I attended the user testing sessions. Some testers provided feedback on text and terminology that was unclear, which will be valuable if the team goes forward with the prototype.
Outcome
So far, CloudBees DevOptics has held two discovery sprints using this process. The first sprint was a trial of the new discovery process. The main takeaway from the first sprint was that the feature the team wanted to implement was more complex than they initially thought. One developer was chosen to take a week to work on a proof of concept for the technical aspects of implementing the feature. A follow-up meeting for the proof of concept is scheduled. For that reason, no documentation has come out of the first sprint yet.
The second discovery sprint was more successful. At the conclusion of the discovery sprint, I was able to write a draft document that includes procedural information and some conceptual information based on the prototype. If the proposed feature is moved to a delivery epic, the draft documentation can serve not only as the basis for the user-facing documentation, but also as an internal single source of truth for the feature.
Advantages and disadvantages
Being involved in a discovery sprint allowed me to learn the what, why, and how of a potential new feature; what it is, why a customer would use it, and how it works. This thorough understanding of the feature is crucial to writing documentation that is focused on what users want to accomplish. Additionally, completing documentation early in the development cycle means that documentation can be released as soon as a new feature is released.
The only disadvantage was the time commitment. Several hours a day were blocked off for the discovery sessions. Since the discovery was not part of a sprint, all the normal sprint work still needed to be completed.
Overall, it was a valuable experience that will lead to more user-focused documentation at CloudBees.
Additional resources
Check out the CloudBees DevOptics documentation here: https://go.cloudbees.com/docs/cloudbees-documentation/devoptics-user-guide/