The task of a business analyst is not just to elicit and document sound business requirements and solutions artifacts but also to structure them in a way that is accessible to a range of stakeholders.
Your raison d’etre is to analyze and articulate the business in a way that improves your team’s ability to efficiently deliver value to the customer. So how does one massage increasingly large and complex requirements sets and solutions artifacts into something that is both feasibly maintainable and broadly useful?
Building a Case for Documentation
We’ve all been there: timelines are tight, budget is dwindling… and documentation is often the first thing to go out the window to spare precious resources.
First, we need to build the business case for good documentation, both internally and to the client.
Good documentation allows us to shrink the time spent understanding the business and the solution so that we can focus on efficiently delivering valuable outcomes to the client.
No one likes to follow breadcrumbs
Imagine being staffed on a brand new, enterprise-level project, and the product owner asks why the previous architect introduced a custom object instead of leveraging a standard Salesforce feature.
Without documentation that outlines both the business case and the technical solution, you’re left in the lurch, hunting down breadcrumbs from the architect’s past, trying to understand the rationale behind a past decision and how it may influence the piece of work you are responsible for delivering now. This scenario is avoidable through concise documentation.
A better way forward
Quality documentation should enable project teams to:
- Understand key business functions, processes, and requirements.
- Clearly articulate how the solution serves the business need(s).
- Communicate how and why a solution was built, given the available tools and resources.
- Quickly digest how the solution fits into the client’s broader technical landscape.
Documentation as a deliverable
Increase accountability for quality documentation by including key artifacts as deliverables in your Scope of Work.
Mutually agreeing on the required artifacts with the client helps to build trust, ensure that requirements and solutions move through an established validation process (to avoid surprises later on), and hold the project team accountable for delivering documentation that will support the solution for years to come.
Tip: It is less expensive to document now, while it’s fresh, than to spend time documenting requirements or solutions retrospectively.
Principles of Good Documentation
The business analyst should be adept at untangling complexity and creating order from chaos. Your role is to provide your team with clarity on the business and to act as an authority on how the solution meets the business needs.
Following the Salesforce Well-Architected mantra of trusted, easy, and adaptable, the documentation you produce should be concise, contextualized, consistent, and connected.
Concise but contextualized
There is a balance to be struck between providing sufficient context to enable readers to understand the ‘why’ behind requirements and solutions without bogging down artifacts to the degree that they become tiresome to digest.
Strategies to improve the readability of your documentation include:
- ‘Decompose’ functional requirements: Following a coherent decomposition structure for your business information helps readers to understand the big picture first and then drill down into lower levels of granularity as needed. A well-structured set of business processes allows your audience to pinpoint the part of the business they are concerned with so they only ingest information relevant to their immediate need.
- Follow Salesforce Architect’s “Diagram Levels” for technical documentation: Pitching technical documentation at the correct ‘level’ helps to ensure that technical audiences (i.e. developers) have the required context they need without being distracted by detail. Salesforce Architects proposes identifying the level of each technical artifact to help readers understand the purpose of the document:
Tip: Each piece of documentation should answer a very clear question. If your team members are consistently asking a question that your current body of documentation cannot answer, consider adding it in and archiving documentation that is no longer serving a purpose.
Finally, only document what’s actually needed. Depending on the scale and complexity of your project, the nature of your documentation should change. Align with your Solutions Architect to generate a list of essential artifacts that are non-negotiable before you kick off.
Consistency is key
Consistency is key, both for saving time and producing high-quality artifacts time and time again. A few simple ways to enforce consistency across your documentation corpus include:
- Drafting documentation standards for use across clients and projects: Whether you’re a freelancer or employed by an established firm, your team should have a set of documentation standards which outline strategies and expectations for producing and maintaining quality documentation.
- Templatize essential artifacts: Produce high-quality template material that you can apply to every project to reduce documentation set-up time.
- Customize only when necessary: Only make customisations to template material, or introduce entirely custom documents where absolutely necessary. Ensure there is a clear question that needs to be answered before introducing a custom document.
Tip: Salesforce Architects and LucidChart have out-of-the-box Salesforce templates, including pre-made ERDs, system landscape diagrams, and more that you can start using today.
Technical solutions connected to functional requirements
A common documentation pain point is understanding the relationship between the technical artifacts and the business function they support.
- Your functional requirements answer the question: “What does the business do/need?”
- Your technical artifacts answer the question: “How did we solve the requirement?”
The gap often exists in the ‘why’:
- “Why are we solving this requirement with this particular solution at this particular time?”
On a platform as prolific as Salesforce, there are often multiple ways to solve for a single requirement. Clearly articulating why a certain design decision was made is crucial to support future project teams in designing thoughtfully into a brownfield org, as well as for the client to be able to understand the solution that they will own for years to come.
Some practical ways to tether your technical and functional documentation include:
- Drafting a narrative solution overview that explains how the solution meets the desired to-be state of the system in plain-language.
- Including a set of key design decisions that outline why certain architecture decisions were made, including the trade-offs and limitations.
- Using a coding system for process flows and referencing which process a technical solution supports
- Writing high-level solution summaries against epics.
- Writing low-level configuration notes against user stories.
Tip: Align your documentation with a central vision for the system. If your client has a vision relating to enhanced simplicity and user experience, for example, your documentation should highlight how the solution supports this vision.
Organizing Documentation Artifacts
Organizing documentation takes effort; however, with an established way of working, the time spent managing and locating important artifacts can be minimized.
Artefact altitude
Document availability and accessibility are not equal – just because a piece of information is available somewhere in the corpus of the account’s documentation does not make it immediately accessible to the stakeholder who needs it at their fingertips on short notice.
In order to retrieve and maintain documentation quickly and easily, there needs to be one source of truth for the information, and it needs to be situated in a logical home.
Consider automation documentation for larger-scale accounts with multiple workstreams. The use case for new automation may be specific to the workstream, but the automation impacts work completed in another concurrent workstream.
- Account-level documentation should contain all documentation that affects the account as a whole – it is project-agnostic. Examples may include:
- Automation overviews
- Key architectural design decisions
- System landscape diagrams
- Comprehensive ERDs
- Roadmap
- Project-level documentation should contain the documentation that is specific to that particular piece of work and would not likely need to be referenced by stakeholders working on another facet of the account. Examples may include:
- User stories
- Physical models for discrete pieces of functionality
- Project-specific risk logs
- Timeline and budget
When setting up your document storage systems, consider where to place certain pieces of documentation to ensure that they exist only once and in the most accessible location for all stakeholders.
Maintaining living documents
We’ve all been faced with the horror of numerous, duplicate documents – unsure of which version is the right one. Make sure that there is only one living source of truth for each of your key documents.
All changes should be tracked as versions, with previous versions filed in an archive to help support the tracking of changes over time while keeping the accessible corpus of documentation free of clutter.
‘In-system’ documentation
Documentation isn’t something that only happens ‘off-system’. Salesforce offers a number of useful ways to contextualize configuration that project teams can take advantage of to support future clarification and debugging efforts.
Some simple in-system documentation strategies include:
- Always adding useful metadata component descriptions
- Adding help text to fields where applicable
- Developing consistent naming conventions for automation and ensuring Flow elements and variables are appropriately named and described
- Adding in-line comments to any custom code and complex formulas to explain the logic in plain language
- Deprecating metadata components using common naming conventions (i.e. zDEP_ prefix)
Summary
Focussing on well-structured documentation will help to:
- Equip the technical team to make informed design decisions that deliver value to the business.
- Empower the client to comprehensively understand and validate their solution.
- Reduce time lost on reverse-engineering, rework, and unplanned work related to retracing past decisions.
By building a coherent business case for documentation that aligns both internal and external teams, following documentation best practices, and structuring your artifacts in a way that makes sense, high-quality documentation is achievable on any project.
Comments: