How to improve specification document process remotely

March 6, 2024
Product Design
Words of wisdom
1. Intro

I was called to audit and improve the writing process of specification document (further referred to as spec) because of the slow turnaround and collaboration issues between different departments.

Before jumping into it, let's agree on what the specification document is and what it is for. While it may vary slightly, the specification document in this company was a file used to document technical aspects of the application. It was designed to outline the requirements and fundamental architecture of the app and used as a primary resource for the following work.

2. Diagnose before prescribing

At first sight, the internal spec writing process seemed complex. So I dug deeper to understand how it works and which parts of the process are faulty and cause problems later on.

In a nutshell, the process looked something like this: the technical lead would build the first draft with the client and then pass it on to the design and development team that would use it as a blueprint to develop the product. Essentially, it was supposed to align everyone's expectations. So far, so good, right? Wrong! Companies are pretty good at sweeping their problems under the carpet, so to an unsuspecting visitor, everything seems in order. I needed more information, meaning more research had to be done. The first place I looked at was the powerhouse of the company that keep the wheels turning - the developers. After talking with them, I found that it may take anywhere from few weeks up to a few months for them to see the first draft of the spec. It would then take another week or so for everyone to familiarise with it and only a couple days to give feedback. I then continued interviewing the design team that would create a separate document with use cases, user interfaces and mockups upon receiving the initial spec. Their wait time was about the same as developers (see figure 1). Needless to say that the two documents produced by the technical lead and design team looked very different. The development team would then use both sources during development. The documents would then get updated asynchronously leading to all kinds of misunderstandings.

Figure 1. Initial spec writing process

The process looked like the relay race where only a single person can hold a baton at a given time while others impatiently wait for their turn. What was supposed to be a quick race seemed like a marathon instead. In the end, it seemed like the first and the last member of the team participated in different races altogether wasting everyone's time and causing miscommunication on both ends.

3. Finding the right problem to solve

Before jumping into solutions we needed to identify the main problem that would generate the most value. After a quick brainstorming session followed by a quick vote, we have identified several important problems.

  • Lack of transparency;
  • Lack of collaboration between both technical and design teams;
  • Unclear process;
  • Two different documents to work from (one too many);
  • Not effective feedback loop;

I like to look for connections and ways to solve multiple problems by solving just a few. If you dig deep enough to find the root problem this suddenly becomes possible. After some discussion, it became apparent that the complete visibility of the process would allow to collaborate on a single document and share feedback sooner.

4. The solution

There is always more than one way to solve the problem. Initially, we noted all possible solutions and then sorted all of them by how much effort it will require and how much value it would bring (see figure 2 below). Then we selected the ones that would bring the most value and require the least effort. That showed us the optimal steps to the solution.

Figure 2. Value vs effort

The first step was to set up a "work in progress" folder where the team would put all moving parts of the spec (client needs, technical requirements/limitations and design assets). The folder was to host all resources in one place providing complete visibility of the current state of the spec. This allows designers and developers to ideate, prototype and test the ideas to fail quickly and provide valuable feedback. This would work in cycles slowly moulding itself into a single document. One file to rule them all (for all the fans out there)!

The second step was to design a process that would facilitate collaboration and sharing feedback. For people to collaborate effectively, they need a defined goal (check), milestones (set by the product managers - check), reasons to do it (check) and support to stay on track (management was more than happy to keep the tabs, so - check). To get the ball rolling, I suggested getting developers and designers on a few initial client calls. This helps to understand what the client is looking for and makes the team feel like an integral part of the process from the get-go.

I left the rest to sort out for themselves. Mainly because we, people in general, are much more likely to continue on a path that we have chosen ourselves. Even though we have not outlined a detailed process to follow (just a basic framework), with transparency and collaboration in place, it was no longer a problem.

5. Overview

Bit by bit everything started to fall into place. Transparency allowed everyone to contribute to the overall development from day one. The newly implemented design cycles (i.e. ideate, prototype, test) helped to improve the initial ideas while they were still on paper. In the end, the overall spec writing process became almost twice as fast and yelled about 25% fewer issues down the road, therefore, became more effective (see figure 3). Previously purely technical document was now infused with user flows, diagrams and mockups. The overall perception changed from an isolated document to a document owned by everyone.

Figure 2. Value vs effort

When we allow smart people to take ownership and work on a common goal great things can happen.

You may also like

Read More