Business photo created by drobotdean — www.freepik.com

One day, while doing some User Acceptance Testing for a new feature, I found myself wondering how QA could have allowed it to pass in its current state. The font sizes were off, the button color was not according to the design, and the line breaks for the text just didn’t look right.

I asked the product manager why these weren’t caught by QA. After checking in with the QA team, her response was “they thought it was supposed to be this way.” That was a clue.

Nobody likes documentation for its own sake. Business analysts may appreciate it as a form of job security, but no executive wants their people pouring hours and hours into documentation that will never be read.

On the other hand, the need for clear, understandable and accurate requirements is just growing. As teams grow increasingly diverse - both geographically, linguistically, and culturally - the ability to bridge these gaps is critical to delivering a polished final product.

The “broken telephone” of product requirements between departments is only exacerbated by the trending WFH environment. Product managers, designers, software engineers and quality assurance must all be aiming at the same target to deliver with quality.

The question is — how to ensure that your product documentation is clear and detailed enough that QA knows what is expected but not so detailed that it more closely resembles a short novel?

Not all software development teams are created equal. There are some personalities who are happy to receive rigid, well-defined requirements. There are other personality types who would be insulted to receive such a well-defined (i.e. you boxed-me-in) task.

Every product leader has to make an honest accounting of their team; assessing the unique skill-sets and individual personalities they are working with. The tools I’m recommending here should be used as a master chef — salt to taste.

Tool #1 — Numbering

This should be obvious, but I have to mention it nonetheless. Larger tasks should be grouped into sections, and each section broken down into smaller numbered tasks. The goal should be that when your QA team is making their review, if they fail requirement number 3.4, it should be clear to the engineer what didn’t work.

If you’ve lumped a number of requirements into a single “number” it leaves room for ambiguity and miscommunication between the teams. Each numbered item should be independently test-able.

Tool #2 — Have a Design System

This is an investment that will pay you back over and over again. A well thought-out design system will help you maintain consistency in your branding and will save many hours of engineer time re-coding CSS over and over again.

These details are the type that usually take up way too much space in your requirements, and by having a full design system, you can avoid re-writing your design specifications across different features. Here’s an example of a design system for buttons:

Tool #3 — Share the design specs

Whether you’re using Adobe XD, Figma, Sketch, etc. I’ve found a huge benefit to giving QA access to see the original files, instead of snapshotting an image and including it in the requirements document. It’s also very helpful for your engineers to help them understand the operational flow.

Tool #4 — Match your numbering to your design spec

This seems a bit tedious at first, but I’ve found that it adds an often-needed level of clarity; especially when remote teams are natively speaking different languages. Combining the text from the requirements document with the images in the design spec leaves very little room for confusion. Here’s an example:

Tool #5 — Test and Learn

This is a general practice introduced by the Japanese called Kaizen. A loose translation is: The growth and learning never stops. Have check-ins with your engineers to hear feedback about the changes you’ve implemented.

Listen to your QA team. Speak with your business analysts, and see if these tools are adding the intended value. You should strive to be nimble, and only implement rigor where it’s needed. How does the master chef know if their food is up to par? When customers keep coming back asking for more. That should be your measuring stick.

From my personal experience, I can attest that these tools indeed worked for us. Our QA department was thrilled, as the requirements they received needed no additional (time-consuming) explanations and they knew that what they were passing/failing was in line with the intended design.

Overall SDLC throughput time decreased as ‘false-negatives’ were reduced and designs were implemented correctly in the first round. Let me know if they work for you!