Common Documentation Storage. Why and how?

Alexey Kiselev
Nov 10, 2018 · 10 min read

Problem Statement

While I’m involved in a project, I’m really trying to store all my artifacts in a project workspace, so it could be reused. It should be by default for Product Teams, but I saw some exceptions there as well.

Key problem here is that there are a lot of unknown, forgotten, restricted artifacts BSA got no access to and because of this, BSA should start their research from scratch.

Every BSA should start the problem research or a solution description with analyzing a business domain and related problems. It’s hard to do while you got no artifacts to start your research with. Another problem is that even the artifacts already exist, it’s pretty hard to find them if this is your first week in this project and your customers are busy with their current duties.

Anyway, this research always require some time — it could be one week or it could be months depending on a scope of your project. Having a documented process, current system, business domain could save significant time and will guarantee (if the documentation is somewhat supported) the correctness of the knowledge source.

Likewise implementation tasks — there are a lot of common areas like notifications, authorization, authentication, profile page, etc. As a rule, these kind of User Stories/Tasks are already exists is Jira, Confluence or other previous project’s documentation and all you need to do as a BSA — find them. I don’t want to cover an area of code reuse, so let’s consider it as an out of scope for our article.

Economical Effect

At first, reusing of the accumulated experience will help BSA to elicit and document more details at the same timeframe. Sooner or later that will be a beneficial practice because nobody could say that this software will serve the needs forever without any changes.

Second point is a bit more important — company could save some money because of the artifacts and knowledge reuse.

Essentially, BSA will require less hours to bring the same results. For example, BSA was not able to find implementation tasks for “Emission” use case and they had to write it down again from scratch, which took like 52 hours for a single person. Let’s assume that BSA salary is 100k $, so the cost of these single duplicated story is 2462$, but what if there are much more duplicated functionalities:

  • Authorization
  • Authentification
  • Restore Password
  • Notification
  • History Review
  • Logging
  • etc

I even saw a startup which offers all these functions above as a ready to go archive. Their argument is that you could pay like 10k$ and receive all basic functions today or you could develop all the same for months. We got all the same with our BSA artifacts.

Let’s assume that our company got a multiple software development projects, each Application got a similar User Stories. Let’s add some variables:

  • X is a hours of BSA work
  • Y is a BSA salary per hour

Every duplicated User Story costs X*Y*<amount of duplicated user stories> for the company.

Why some Companies still don’t have these documentation repositories

Here are main points why companies still don’t have repositories with project artifacts:

1. There is no shared workspace with search capabilities where BSA could store their artifacts:

1.1 Sometimes BSAs are not able to find a shared space with the documentation

1.2 Search capabilities are not that flexible or a naming convention is not allowing to find something based on a logic sense keywords. At this point some BSAs prefers to explore everything by themselves instead of spending too much time searching.

1.3 Workspace exists but no access for BSA there.

2. This is funny, but sometimes company could have too many workspaces with search capabilities where BSA could store their artifacts. So, BSA should research all of them.

3. Documentation is not standardized. This is a rare thing, but sometimes documents are not structured, not consistent, etc. BSA should spend too much time to fully understand an information from there. For example:

3.1 No connection between a business need and a solution,

3.2 Document is not actual,

3.3 Outdated notations (IDEF or others),

3.4 Etc.

4. Management and team members are not involved enough in the project.

5. Management thinks that they are too “Agile” to do things like that.

Photo by rawpixel on Unsplash

Solutions

Here are some obvious ways to resolve the problems specified above:

  • Implement a space with all projects names and short descriptions.
  • Implement single space where BSA are able to store all their documentation.
  • Set up a documentation standard across organization.

If your management is not initiative enough, Lead BSA should be able to consolidate all the problems related to unstructured document storage and specify all benefits of using this storage.

Honestly, there is no need to purchase some products created to manage requirements only like Rational RequisitePro or analogs, because, for example, Confluence or Google Drive are flexible enough to handle documentation. Key points here is a security restriction and your management cooperation.

Project documentation storage

One of key problems related to the search capability — it is very important to classify and tag all the documents like you are splitting Jira tasks via components and tags. This will help BSA to find relevant or related documentation.

Search through attributes will be really helpful as well, unique identifiers will be really helpful for references, traceability, etc. This sounds pretty obvious today, but 10 years ago that was something you had to point out.

At this point we can do the next statement:

  • SVN and VSS are not welcome as a solution
  • Microsoft SharePoint and IBM Lotus are too heavy for our task
  • Custom solution with a database is definitely over budget

So, I would say that Confluence page with a list of all projects and hyperlinks to the Confluence Spaces is something I would consider as the best solution.

Documentation structuring

Purchasing any tools specified above is not a solution and will not help you to resolve all the problems. BSA must follow company’s standards and audit existing documents.

For example, it’s much easier to find out the project of the particular requirement if you’ll store the document based on the next naming convention.

If we will follow next pattern

<Project name> <Requirement number> (for example, “PRJ1 REQ12”), it will be really hard to understand the document content.

Compare to

<Document type> <Project or customer> <Business Area> <Requirements or UI name> (for example, “Requirements Salesforce CRM Common Dashboard Implementation”)

Proceeding to the storage structure, we could highlight next areas:

  1. Single page with all projects. All BSA must have an access there.
  2. Documents ready for reuse. These documents should have no customer specific or confidential data (screenshots and examples must have no confidential data as well). All these documents must be available for all BSAs.
  3. Project documentation. Multiple replicas of storage areas tied to the specific project. Could have a restricted access.

This is not that important how you will organize a typical structure of the project, but just as an idea:

  • Introduction
  • Business Needs or Problems
  • Requirements (Use Cases, User Stories)
  • UI description
  • QA
  • Environments
  • Customer

Ready to use documents could be split according to the business needs like:

  • Authorization and Authentication
  • Email templates
  • Notifications
  • Common fields
  • Warnings and Errors
  • Scheduler

Why different areas are that important to store documents — because of confidentiality, access and proofreading. All documents in the “Documents ready for use” could be considered as the latest and the greatest, while project documentation requires proofreading, confidential data wiping out and could be considered as a risky to reuse.

If we got 2 different areas and know the difference between them, it makes sense to clarify the process of transferring documents from one area to another. Because we mostly care about “Documents ready to use” area, I’ll cover how documents could appear there:

1. First step is a decision point that document should be added to the “Documents ready to use” area as an etalon. We could make this decision based on prediction that this document could be reused in a different project or based on a fact that the document exists in a project and should be reused in another. We could call the first case as an “art of the lead BSA and management” because it’s pretty hard to set up metrics here.

2. If the document passed #1 then:

2.1 Lead BSA must validate documents against company documentation standards. If any inconsistency found that document should be edited by the document’s author or any other person and re-validated.

2.2 Checklist should be really helpful to speed up the process and improve the quality

2.3 It’s pretty hard to validate the content quality. Even if requirements are SMART (specific, measurable, achievable, realistic, traceable), it’s always possible to have a separate view on wording and statements. This is going to be out of scope in this article.

3. If the document passed #2 then we can add it to the “Documents ready to use” area. All search attributes should be set. You could also work on the searching parameters to make sure that it will be easy to find a document based on synonyms or related business area words.

4. Next step of the document lifecycle is support. It’s pretty good to track how many times this document reused, if it requires changes for every project, etc. As an idea, for Confluence pages you could add a macros to track the number of views.

Even if the document requires changes for every project implementation, it is important to keep original one document as is. BSAs must tailor the document for their projects and keep it in the project repository with a link to original document (for QA purpose).

Document support

If every step of the process followed properly, it will be no need to update the document unless any technological or law changes. Here is a process:

  1. Your documents storage should have a version control (like previously mentioned SVN, GIT, Confluence and Google Drive). Every version should have a unique identifier and all project which reused our ethalon document must have a link bot to the document itself, but to the particular version of the document.
  2. Every updated version should be verified

At the end of the ethalon document lifecycle it should be archived, so, all project documentation will preserve links.

Document reuse

If documents were reused in project by junior BSA, it makes sense to validate them. In other cases you could consider these documents as qualified for implementation (you could run them against document quality checklist if your company have it).

Pros and Cons

Side benefit of this document reuse is that you will be able to track changes in related projects. As an idea, if you got a change in Project1 and the same document reused in Project2 and Project3, you can do a better impact analysis and should be able to notify your customers that update required (this is really important if you have a law related systems).

Main disadvantage of this document reuse is an effort required to organize the process and document storage itself, support it and keep updated. The best way is to collect statistics to be sure that you did a right (or wrong) decision.

I made an assumption that we could apply an update formula for our case:

(X*<amount of duplicated user stories> — (K + M + L))*Y

Where:

  • K — extra BSA time effort to move the document to “Documents ready to use” area.
  • L — total time required to adopt etalon document for a specific project.L is inversely proportional to K. Simply said: the higher is K the lower is L.
  • М — some time the company spent to apply the specified process (could be shared among etalon documents).
  • X is a hours of BSA work.
  • Y is a BSA salary per hour.

If you found a good document for universalization, then L of the single project will be always less than X*Y, so, more reuse — more economy.

I wanted to use a history as an example, but this going to be too beneficial, so I decided to use objects linkage as an example. I wrote at least 4 requirements specification documents for object linkage in different 3 companies during my career). You can put you hourly rate as an X, but the rest looks like this:

(6h*(4h-1h) — (3h + 5h (Confluence page) + 3h))*Y -> ~7h*Y economy for 4 projects.

Assuming that the average BSA salary for Y is 83716 USD (based on https://www.indeed.com/salaries/Business-Systems-Analyst-Salaries), hourly rate is about 39.64 USD, so in this case we will help so save 277.46 USD per four requirements specifications reuse, which is 277.46/(4*6*39.64)*100 = 29.16% economy. I believe that the final amount is even more optimistic, because of the quality improvements.

Conclusion

  • This concept definitely worth it to try if you are working in a product company where your customers often requires customization of some features while core features are always the same.
  • For the product company like Intuit that’s not that useful because you don’t need a features duplication unless your company wants to run a different product but with some common features (like Intiut got for Mint and TurboTax).
  • It is also make sense for the product companies like Salesforce to share their documents with requirements, so customer’s BSAs will be able to reuse them in their documentation. As a side effect — Salesforce software will always 100% fit customer’s requirements.
  • It would be great to have a worldwide storage of such kind of documents, but unfortunately this will be totally restricted because of NDA and some other related problems, but this could be a totally different research.

Authors

Thanks to Jane Pavlova

Alexey Kiselev

Written by

Lead BSA, Product Manager from the Bay Area

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade