How to Add Value to a Project Using Smart Knowledge Sharing Strategies (Part I)

Author: Adriana Beal

Is there value in keeping system documentation up-do-date?

Keeping system documentation up-to-date is a challenge faced by many business analysts. In discussion forums, it is common for this concern to be raised in questions such as, “How do you avoid the problem of having only one or two BAs with full understanding and latest information about a software project, creating a critical dependency and bottleneck?”

We all know how challenging it is to produce and maintain complete, accurate, and readable documentation throughout the project life cycle. Tony Heap, in a comment posted to his excellent article, A Case Study: A Business Analyst on an Agile Project, wrote:

“I agree that good documentation for a (bespoke) system is an asset – the benefits are obvious in terms of training and hand-over. I used to think that it was a no-brainer that we should strive to produce such documentation. But these days I’m not so sure.

My experience is that it is extremely difficult and time-consuming to produce and maintain comprehensive, readable documentation. What I’ve noticed is that unless the docs are perfect, they are pretty much worthless – because people are never sure which bits to trust. I’ve also noticed that most people learn and understand a system best by either looking at it from the outside (i.e. via its user interface) or from the inside (i.e. via its source code).”

As Tony points out, even a small piece of information that is incorrect, obsolete or incomplete can make an entire document worthless, because people won’t be able to trust what they read. On the other hand, the benefits of good documentation often go beyond training and hand-over purposes. Many of us have been involved in incremental/iterative projects in which stakeholders are constantly in need to confirm what the system does, or was supposed to do, under different scenarios, both before and after the system is put into production. Although many people may learn and understand a system best by either looking at the actual application or source code like Tony suggests, in a dynamic organizational environment there will be many situations in which project stakeholders won’t have the time to research an issue in this manner, or the answer simply won’t be there.

What user goals does system documentation support?

Examples of how such needs arise in organizations include:

  • A user is due to complete the user acceptance testing for a feature that is being modified. As he works through a normal usage scenario, he notices that a validation that used to make a field conditionally required when another field was populated, is no longer in effect. He wonders whether this change was requested by one of the business stakeholders–if not, it should be reported as a defect. The only documentation available is the high-level user story that was supposed to serve as a “reminder for a conversation” between the developers, BA, and key stakeholders, and it doesn’t answer his question. How can he quickly confirm if the removal of the validation was introduced by design, or involuntarily as part of the change that was actually requested?
  • An executive is about to send an alert to customers to inform them about an unplanned system outage. The system being used to send this type of alert to customers has just been put into production, and it’s the first time it will be used when there are already two other notifications in the queue, waiting to be released at a future time. The executive remembers that there had been a back and forth about what should happen to notifications in the queue when a notification is created for immediate release. Will they remain undisturbed in the queue, go back to a draft status, or (the most concerning option) get released at the same time the alert is distributed? The SRS that contains the actual requirement has more than 150 pages, so she picks up the phone to call the business analyst assigned to the project, but only reaches her voicemail. How to quickly find out what will happen when the executive clicks “send”?
  • A developer is trying to estimate the effort for a feature in the backlog. He identifies two possible solutions, one simple, one very complex. The simple one implies a relatively small change in the way an element is displayed in the screen. Not knowing the rationale behind the way the element is currently displayed, it is impossible for him to come to a conclusion. Without consulting the BA or product owner, the project manager is unable to confirm whether it would be acceptable to make the user interface change that would allow the team to go with the simplest solution.

This list could go on and on. As business analysts, we are constantly sought out by developers, designers, project managers, system architects, business stakeholders, testers, contractors, and all sorts of stakeholders who need an immediate answer for a question about system behavior. I’m sure many BAs, like me, would prefer not have their work interrupted unnecessarily, or to become a cause of frustration for stakeholders when they can’t be reached to provide an answer in a timely manner.

Can code become system documentation?

The suggestion from some agilists, that “the code becomes the documentation,” does not solve the dependency on the availability of a technical person capable of reading the code to provide the answers. Also, looking at the code may allow stakeholders to confirm how the system is actually working, but since defects and design errors are pervasive problems in software development, this method can’t be relied upon to provide complete information about the system’s intended behavior.

A better option, found for example in test-first development approaches, is to use test cases (written even before the code is built, for manual or automated execution) as means to document the expected behavior. Still, test cases describe inputs, actions or events, and their expected results, and again may not necessarily be written in a manner that is easily understood by non-technical stakeholders. Even when a test case is written in a user-friendly manner, looking for the answer to a question about system behavior can become very time consuming (in the second example above, the stakeholder would have to know how to search for a particular scenario that tested the creation of an alert with other notifications already in the queue).

What to do, then, when time is short, other competing demands prevent the BA from maintaining system documentation up-to-date, and the situation is affecting the productivity of other stakeholders? Have you faced this issue in your career? In Part II of this article I describe a method that has worked well for me in various projects.

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.


  1. Holly, thank you for your comments. Your experience reflects mine and I’m sure of many other BAs. The second part of the article is about to be published, and I look forward reading your observations and suggestions after reading about the approach I’ve been using to solve this problem.

  2. Holly Martin says

    Timely article. I’ve just been tasked with coming up with a way to consolidate all the great knowledge and info our BA’s collect on projects so it’s not lost.

    @Adriana: I like your reference to a “smart knowledge library”. This is the sticking point I always have. That once it’s created document becomes immediately out of date (kind of like the Blue Book value of a car you just purchased, right after you drive it off the lot). You are exactly right that trust factor depreciates with how old the documentation is (and sometimes based on who created it).

    I often remind myself that the presence of any documentation at all is a bonus for me as a BA. It gives me a starting point for my analysis. If I go in assuming it might not be accurate, then I don’t get frustrated. I plan for additional time to investigate these pieces to confirm functionality (especially when working on legacy software conversion projects). I frequently engage my QA team to test some pieces early, to verify points in the document I’m analyzing. But I empathize with others in that resource availability to decode the code, or test scenarios, can often become the bottleneck in requirements phase.

    I’m not sure if a requirements tool (meaning software package) necessarily solves this problem. It can certainly help to consolidate information so it’s easier to locate and search, but a tool is only as good as the input and process behind it. I feel like an organization needs to be at a certain level of requirements process maturity before introducing yet another tool into the process.

    Looking forward to part 2 and learning more about how others tackle this issue.

  3. Nick, if you went a little further, you would have written the second part of the article for me :-).

    Thanks for your adding your views. I look forward continuing the conversation after Part II is published!

  4. It’s nice to see others feel my pain; miserly loves company. The user goals listed seem to pop up project after project. In environments where the lifespan of a single system is more than 5 years, where turnover happens, where communications occur to more and more people as times goes on, documentation becomes more important.
    I see two ways that this can go:
    1. Requirements documentation on a project has 3 parts:
    * As Is – How the system works before the change
    * Change – The Change being proposed
    * To Be – How the system will behave after the change
    If, during the requirements documentation, you take care of all 3 aspects for each and every change, all you need is the To Be documentation. What I assume many document (I’m guilty), is one type of documentation that is a combination of the Change and To Be. So we’re stuck with no single To Be document after a project (which after the project becomes the As Is of the next project).
    There is just no simple way to document those 3 aspects for each requirements. We’d probably be writing documentation more than making decisions and eliciting requirements.
    2. The other way is to change the way we document. Stakeholders hate reading our requirements. Text, diagrams…who wants to go through a document, and make sure I documented a decision we made 5 days earlier (which has already been coded and tested)? I think another medium is necessary. Video requirements? Should the training video be the final requirements package? Should we move requirements out of documents into a more social environment?
    I don’t have answers, though…at least not yet.

  5. @Brandon: I’m starting to think that this 2-part article is going to be cathartic for many of us :-). Thank you for the compliment, and it’s rewarding to know that the article helped spark some new ideas!

    I feel your pain about the CMS system — the sheer number of workflows and different roles can quickly become a nightmare, especially difficult to maintain without proper documentation, like Laura previously said.

    The fact is, except perhaps for the “critical dependency” person that everybody has to run to in order to get information to perform their job or make a project decision, we all need access to readable, up-to-date information about system behavior and the context around that behavior. From the support person responsible for analyzing reported incidents/defects like Dave described, to the business analyst being hired to facilitate change like Laura described, to the stakeholders trying to make decisions about a to-be process without enough information about the as-is process, like you described.

    Like you, I’m constantly working to find the right balance with project documentation. Still, we are trying, and making progress, which already puts us ahead of the curve ;-).

  6. Laura, your story is similar to mine as well. I came into a situation where a content management system has been implemented very poorly and there’s little to no documentation supporting decision-making or how the system is shaped at this point.

    I am leading a team across multiple departments and working closely with executive stakeholders on re-implementing the content management system. The caveat is the CMS is really enterprise-wide. There are more than 500 active users at any given time, and the workflows and roles implemented in the system must be scalable and executable for a variety of user personas.

    Back to the discussion of documentation, I am still working my way to find a reasonable documentation level that won’t create “documentation paralysis” (should I trademark that?) and create a level of buy-in for the end-users of that documentation.

    Great work, Adriana, and thank you for sparking some new ideas in my quest to create a positive relationship with documentation amongst my stakeholders.

  7. Laura, thank you for sharing your experience, and serving as an example to other BAs! I definitely agree with your view that undocumented systems will only become more complex and more difficult to maintain with time.

    I see a tendency among some BAs to just shrug and say, “oh, well, it is impossible to have complete and up-to-date documentation, so let’s just forget about it”. With that frame of mind, they miss a huge opportunity to build credibility and add value to their roles by removing a pain point for their organization through better knowledge sharing techniques. Perhaps the current maturity level of most organizations do not allow them to see the value in your initial consulting business idea yet, but I’m sure all your clients were able to realize the value of the wrap-up activities you describe (even if only after you left ;-).

  8. This is a very cathartic post for me. In my second BA role I joined an organization that had no BA process and very little documentation. The understanding of the business was largely in the head of one sr. developer, a DBA, and the VP of operations. And the rules were brittle and complex, so the business had a tendency to break itself when changes were made.

    I actually started a pet project to document the heck out of the system and the business rules and made a fair start. I was largely limited by the time I had with the SMEs. As you can imagine since they were so knowledgeable they were also in high-demand. My approach was to document in use cases, as that is the technique I knew at the time, and embed the business rules in them (within a special section at the end of each use case). I also used each new project as an opportunity to discover a new slice of the system and slowly build this system documentation.

    What I learned from this experience is that left untouched and undocumented, systems will only become more complex and more difficult to maintain. The cost of discovering the rules later was significant, both in the time I spent with the SMEs, the time they spent going through their own code to answer my questions, and the break/fix mentality within IT.

    So, perhaps this has unduly influenced me since as I tend to ensure that each project has some sort of a wrap-up phase that includes updated documentation and push for this sort of documentation at every turn. In fact, my early consulting business was founded on the idea of focusing on just this sort of diagnostic requirements exercise as a strategic organizational activity. Of course, that line of business never really took off…which probably speaks to the need for a more balanced approach here.

    Looking forward to your next article Adriana. I am anticipating a great solution to this dilemma!

  9. @Dave: thank you for the great example that illustrates how you don’t need to represent complete, end-to-end system documentation to add value to the project and the organization. In your case, reducing the effort necessary to analyze reported defects and incidents was a concrete benefit to be achieved from developing a “smart” knowledge library that focused on what really mattered to the call center/help desk team. You will find that the second part of the article describes a technique that entirely agrees with your approach!

  10. Dave Schrenk says

    For one project that involved replacing our enterprise processing system, we created a “First Line of Defense” team that was responsible for analyzing every reported defect / incident to determine if it represented a defect or if the system was functioning as intended. There were many components to this system and there was no single person that knew all of the end-to-end functionality at a detailed level. And, as usual, the documentation that was created during requirements and design was not kept up to date to reflect things that might have changed during construction, testing, or post-production support. So, this team was comprised of a group of the BAs that possessed as much of the knowledge about the system as possible. We then documented the results of our analysis so that the call center / help desk could begin to build a knowledge library. While this obviously did not represent complete, end-to-end system documentation, it, along with the original requirements, design docs, and defect resolution notes served as an extensive library that explained the intended functionality of all components of the system.

Before you go, would you like to receive our absolutely FREE workshop?

(No formal experience required.)


Quick Start to Success
as a Business Analyst

By signing up, you agree to our Privacy Policy.