What Makes Good Requirements Documentation?

Whether you report to the business or to IT, BA’s all over are expected to deliver the same thing, documentation that is clear, testable, and has lasting value (when properly maintained) once complete.  Whether the project utilizes a waterfall or agile approach, the documentation should be clear, understandable and complete (“complete” can be defined differently depending on the methodology).  The goals for documentation are understanding and approval.

Ask a BA just about any question and the response is likely to be some variation of “Depends” or a real response immediately followed by specific conditions needed for that answer.  This shows the BA is thinking more deeply about the impacts and response than perhaps was originally intended.  There are lots of articles and blogs out there telling you how to write better business analysis documentation.  I’m going to take a different approach – I’m posing a series of questions about your documentation that are designed to make you think about what you are producing so you can produce good documentation.  When answering these questions, ideally, you will not be answering “Depends”.

Big Four Bridge. Source: U.S. Library of Congress, Prints and Photographs Division, “Built in America” Collection

I present these from the perspective of a BA who prefers documentation that is a blend of models / visuals and writing as I feel no one form suits all learning styles.

The following list of questions can be considered a process to think about that might help you provide the value expected of a BA as it relates to complete documentation.  The biggest challenge a BA faces in creating good documentation is finding a balance between being complete and being more like a paperweight.

  • Have you read the document yourself, from start to finish?
  • Is it clear what the problem / opportunity is that’s being addressed by the project?
  • Have you defined who the expected / intended audience is for the document?
  • Have the approvers read portions of the document as you created it or were you waiting to have the whole thing done before letting them see it?
  • Has anyone outside of the project team (business or IT) read the document?
  • Have you had anyone responsible for testing read through the document?
  • If / when others read it, do you have to explain things or are the answers already provided by pointing to other parts of the same document?
  • If you are not using a “standard” company template, do you think the document is well organized and has the right flow of information (based on comments from readers)?
  • If your audience is comprised of both business and technical, do you mention which parts are most relevant to each group?

I hope that the process of answering these questions will lead you to better, more complete documentation and gets you to speedy approval (because it is well done and complete).

>>Improve Your Requirements Writing Skills

Looking for practical ways to reduce requirements defects while also improving your requirements specifications? Check out one of our business analysis training courses:

At Bridging the Gap, we help you start your business analyst career and gain confidence in your business analysis skills.

Free Training - Quick Start to Success

(Stop the frustration and earn the respect
you deserve as a business analyst.)

Click here to learn more

By signing up, you agree to our Privacy Policy.

Comments

  1. Anurag Mishra says

    Requirements document must be organized into the following major sections:
    • List of Requirement Documents
    • Inter-Dependencies Among Requirement Documents
    • Naming Conventions
    • Documentation Guidelines
    • Pending Tasks

    Documents which can be used for requirement gathering is Use Case, Report specifications, BR Catalog, Workshop minutes etc.

  2. Steven A Jones says

    Dave,
    I love the phrase “lean requirements development”! Another step in the growth of a BA by asking them to look at the requirements themselves to make a decision regarding relevance. I think we can all look the title of BA and realize it isn’t just a dime-a-dozen widget to just plug in… why should we be expecting to blindly follow along with a template that might not have “required sections” that have no value for the work you do. A perfect example: I work in a data warehouse dealing with data transformations and the movement of data from one step in the process to another but I am sometimes asked to use and strictly follow a template that asks for screen mock ups. In those instances, I need to put either “N/A” or some other textual write up to justify why I don’t have anything within that specific heading. (Wasted space, wasted effort)

    I would agree with those required components / procedure of the final, delivered documents.

  3. Dave Schrenk says

    Hi Steve,

    I completely agree with you. We recently stopped calling our requirements template a “standard” and now refer to it simply as a starting point that includes best practices. Each BA should tailor it for their project needs because not all of the best practices are needed on every project. I have talked about our new approach as “lean requirements development”. Only do what is needed for you, your stakeholders, and your team to be satisfied that the requirements are complete and accurate and to proceed with design and construction. The only best practices that I continue to expect every BA to adhere to are assigning a unique identifier to every requirement, prioritization, and some form of traceability back to the goals and objectives of the project.

    • Adam Bradley says

      @Dave,

      >>The only best practices that I continue to expect every BA to adhere to are
      >>assigning a unique identifier to every requirement, prioritization, and
      >>some form of traceability back to the goals and objectives of the project.

      I agree 100% with what you state above.

      Regarding the use of templates, I am yet to come across one that suits all projects. Luckily, where I work we do have a template however it is not mandated that BA’s must strictly adhere to it, instead it is there more to act as a guide. I think that by asking a BA to stick strictly to a requirements template is akin to forcing a Project Manager to use a standard project plan for all projects…..it’s simply not going to work.

  4. @Steve – Thank you for your more inputs on documentation.

    As far as consulting; Yes my domain experience(Manufacturing, Marketing and sales) for me as played vital role to pitch in new ideas and solutions to the stakeholders; this helped me to create a win-win situation.
    I started my career as a developer than moved it more of functional role over a period of time.
    So in my resume i have kept “only keywords” as responsibilties and have given more importance on accomplishments explaining in detail.

  5. Steven A Jones says

    A good part of the balance is in providing the appropriate level of detail for the stakeholder reviewing. Also, the “just enough yet complete” approach takes into account the diminishing value of further analysis / documentation because it would take more time to produce than the additional value you would receive from its completion.

    Glad to hear the consulting has worked out so positively for you so far. To me, being a BA and consultant is about managing the value you bring to the table. Domain expertise certainly has its place but it can limit your professional flexibility, whether you are coming from a business or technical domain specialty. And this is totally in alignment with the usual BA answer fo “Depends”. Consider “balance” in the same way, there’s an evaluation that needs to take place before putting something (requirements doc, process flow, even a resume) in front of others to review. You need the right balance – and that’s a development item most of us can continue to improve on.

  6. @Laura – Thank you for your comments.

    I will go through the link and all the articles which are available and then i will get back to you for more details.

  7. Great discussion here – I am a big fan of just-big-enough documents to ensure alignment and clarity. Often this means I have layers of documentation, some of which stakeholders never see as I use it just to help ensure my analysis is complete.

    Akarsh, as far as consulting, you might check out the posts in the Contracting/Consulting category. There are some interviews and tips. This area is by no means complete, but there is some good info over there.

    http://www.bridging-the-gap.com/category/business-analyst-career-advice/business-analyst-contracting-consulting/

  8. @Steve – Thank you for inputs and suggestions.

    Yes your right on documents; i have maintained the lengthy documents for all the projects for complete understanding so that if i any day move out of project people taking over from me should be able to understand it clearly.
    From the stakeholders point of view/interest i am maintaining and using more of visual documents for there understanding(sometimes this helps me to avoid creating prototypes as i would captured visuals using PowerPoint)

    As for Consulting BA, i am also slightly doing the similar kind of work for sometime now using business domain expertise to propose new ideas and solutions for projects; so far it is working wonders for me.

  9. Steven A Jones says

    Akarsh,
    I typically think of templates as a guide to helping get the necessary information necessary, and the template you refer to was probably assembled by a group who had considerable experience on projects. Just as IIBA’s BABOK does not claim to be the single source of all information for BA’s – it is, in fact, titled “A Guide to the Business Analysis Body of Knowledge” – templates likely won’t contain sections that are relevant for each project or even each IT area. I work within a data warehouse and I have yet to see requirements templates cover some of the unique work done here. Another example of a unique document template would be one for reporting only. Each company is different in terms of how strictly you need to follow templates, so there is no single answer for that question.

    Balancing volume to detail is one of the items BA’s need to improve at for sure. As you mentioned, no one really wants to look at a really thick document but you do want them to be complete for understanding. The idea of the document set itself is to be a source for more answers than a source for questions. We could all probably use some improvement in our writing to get to the point more quickly and effectively, which would reduce the overall size of the documents.

    As for Consulting BA, I leverage the BA skills and occassional domain (tech or business) I have developed over the years. Coming into an assignment willing to research and ask “simple” questions of the business or technical side in order to communicate more effectively goes a long way., they are subject matter experts for a reason.

    Steve

  10. Mohammed Arif says

    Thanks Steven, I’ll find….

  11. @Steven – Great Article; i think you have highlighted some great points in the article.

    What i would like to say is even though we have a standard template we might not be able to follow it for all the projects from the stakeholders point of view. As we stakeholders out rightly mentioning they don’t want a documentation which is too lengthy and they just do not have time to read it and go through a lengthy one; but sometimes if you try to shorten the document we end up missing the key points. I think keeping visuals in the documents will solve lot of problems and helps in understanding better.

    I am trying to keep documents to be shorter with visual and keeping in mind both business and technical team understand the parts that are relevant to each other.

    What’s your take on having documentation based on projects/stakeholders requirements instead following the same template all the time ?

    This question is outside this article; when i read about yourself i noticed a key point it says you do “BA in consulting” and i find this interesting; i would like to know what all roles and responsibilities you play when carrying consulting being a BA? Is there article which you have already written on this?

    Thanks and Best regards,
    Akarsh

  12. Steven A Jones says

    Thank you Mohammed.
    There are several sites which host free templates (business, funtional, etc) that you should be able to find through any search engine.

  13. Mohammed Arif says

    Nice article, can I’ve a template of Requirement document.

Comment

*