7 Steps to Writing Better Requirements Documentation


In a recent article on the Top 10 Skills a New Business Analyst Should Shore Up On, #5 was identified as writing requirements specifications.

In a new business analyst role, typically there will be a few types of requirements documents that are most commonly created. If you landed the job without those specific skills, you’ll want to hone your skills to ensure you can deliver what’s expected of you.

7 Steps to Writing Better Requirements DocumentationIn this article, I’ll go through 7 steps you can take to write better requirements documentation or learn how to write a new type of requirements document.

Step 1 – Review Your Organization’s Templates

There’s a funny thing about these terms like “Software Requirements Specification”, “Business Requirements Document”, and even “Use Case”. From organization to organization, what is involved in creating one of these documents can vary widely. Getting your hands on your organization’s templates for these deliverables is important so you don’t make assumptions about what should and should not be included.

When I work with new business analysts, I often hear loads of misconceptions. Here are a few of the most common ones:

  • I need to create UML use cases – what kind of visual model is this? (While an actor use case diagram is a valid UML diagram, the textual use case model, which is what is typically required, is not specified in UML.)

  • In order to create a business process model, I need to use BPMN right? (Not necessarily, most BAs still create simple workflow diagrams to visualize business processes.)

  • I’m being asked to create a BRD (Business Requirements Document) and that means I only need to focus on the business requirements, right? (Not necessarily, most BRD templates I’ve seen include user, functional, and/or system requirements too.)

Many of these misconceptions sound quite reasonable. That’s because it’s not until you see what your organization’s template really contains that you’ll be able to interpret a general request and translate it into specific expectations.

Some organizations lack formal processes and templates. When there is no template, you are starting your template from scratch and that means it’s up to you to translate the general request into a more specific type of document. In this case it’s a good idea to work from a trusted outside template and then get feedback early and often on the template itself to ensure it meets your manager’s expectations for your work on the project. But, we’re getting a few steps ahead of ourselves, because even without annotated, easy-to-use templates, you may be able to get your hands on work samples. Let’s talk about those next.

Step 2 – Look at Work Samples

Whether or not you have a template to use as a starting point, work samples show you how to input information into the template and what the expected work product should look like. Preferably you’ll want to find work samples from internal BAs, but a second-best is to see work samples from a BA outside your organization.

Review the samples to understand the purpose of the document, what kind of information is included, the level of detail requirements are specified in, the type of language used to specify requirements, and the adjustments made to the template. This will give you a starting point when creating your own deliverable.

Step 3 – Fill-In Any Learning Gaps

With templates and/or work samples in hand, the question to ask is “can I create something like this?” Perhaps there are visual models that you haven’t seen before, such as workflow diagrams or domain models. Perhaps the technique used is unfamiliar and you need to learn more about it.

On my first agile project, I needed to learn how to write user stories. While I’d written functional requirements, use cases, and a variety of other specifications, I’d never written a user story. I ordered an authoritative book on the subject and used it as I worked through my first draft, which is what we’ll talk about next. (Training classes and webinars are also good options.)

Step 4 – Create a First Draft

We learn by doing. Taking a class to learn how to theoretically write a user story is one thing. Sitting down and writing a user story is another thing completely. Creating a first draft of a requirements document is an opportunity to apply what you learned.

Use the templates and samples you have at hand, the how-to information you’ve accumulated, and give it your best shot.

Before you solicit outside feedback, it’s a good idea to conduct a self-review against the primary principles of what makes a good requirement. As defined in the BABOK® Guide, those are:

  • Cohesive,

  • Complete,

  • Consistent,

  • Correct,

  • Feasible,

  • Modifiable,

  • Testable, and

  • Unambiguous.

Step 5 – Solicit Feedback from a Trusted Expert

When improving your requirements specifications, feedback helps you improve more quickly and effectively. You could spend hours on the web learning about a technique and revising your deliverable, thinking and rethinking requirements against a particular format and set of quality criteria. Or you could spend a few hours putting together a rough draft, identify your questions and uncertainties, and have someone point out your flaws for you.

Which path sounds easier?

While embracing feedback can be difficult, it speeds the learning process up tremendously. Ideally an internal BA will review your work or perhaps your manager can fill requirements reviewer role. Sometimes that’s not an option or the feedback you receive isn’t very actionable. For example, “this document isn’t clear” isn’t feedback you can work with” while “when you use the word ‘and’ in your requirements, it’s often a sign you are combining two or more requirements into one” is something tangible you can work with and improve from.

Seeking help from an outside mentor who can provide actionable and constructive feedback can often get you leaps and bounds ahead of your peers.

Step 6 – Update Your Deliverable

With feedback in hand, you’ll want to update your deliverable. Sometimes this is an iterative process where you update, receive more feedback, and update again. New improvements can reveal new flaws. Remember, it’s about the learning that’s happening.

Continue to update your deliverable until you are confident in your output and the feedback that comes back is relatively minor. While a requirements document may never be perfect, it should be in relatively good shape (from a formatting and language perspective) before it goes in front of stakeholders, which is what we’ll talk about next.

Step 7 – Solicit Feedback from Your Stakeholders

Finally, you’ll be ready to get feedback from the people who matter most – your stakeholders. Often we think that as the BA we should have a fifth sense about exactly what it is that our stakeholders need. The reality is, that they know what they need, often better than we do. Ask for feedback early on and create specifications that meet those needs. Ask for feedback of draft or close-to-final deliverables to understand what adjustments would make your documentation more useful or easier to understand.

Your stakeholders are also critical in determining if your document includes the right information – i.e. expresses their business needs and requirements and is implementable or testable. They may not be able to tell you if the requirements are expressed appropriately, but sometimes you can gather this feedback indirectly. For example, if a particular requirement causes confusion or generates a lot of questions, that’s a good sign that further analysis or rewording for clarity is needed.

I’ve found that reviews, while they can be conducted via email, are often best done in face-to-face or virtual meetings. This allows you to ask follow-up questions about the feedback and you’ll naturally receive more and better feedback. And that really leads us back to facilitating meetings which was #1 on the list of BA skills to shore up on!

>>Improve Your Requirements Documentation

Learning a new requirements technique can seem overwhelming, but when you break it down into steps it’s a much easier process. Just keep moving forward, one step at a time, and you’ll be writing better requirements documentation or a new type of document in no time!

Also, rest assured that most of the skills you practice in creating one requirements document transfer well to others. Earlier I mentioned writing user stories. Once I got a handle on the syntax and format, I found that my deep experience writing use cases and specifying other types of functional requirements made sure my user stories were clear, implementable, and testable.

About the Author: Laura Brandenburg, CBAP is the author of How to Start a Business Analyst Career, the host of Bridging the Gap, and offers a BA career planning course (it’s free) to help you start your business analyst career.

Like this article:
  35 members liked this article


JohnUnger posted on Friday, September 4, 2015 9:09 AM
Thanks, great advice. I'll definitelly use it. Because I have some problems with that and always use assignment writing help for proofreading and editing some details.
Only registered users may post comments.



Copyright 2006-2024 by Modern Analyst Media LLC