What are the best practices for documenting the current and desired states of a system?

Focus on: Key criteria that defines the success of the desired outcome - moving from existing to desired solution and architecture. Whether it is business problem, features or technical architecture focus on less than 5 top items. Document key features you like in existing system and also the key pain points that you want to avoid with desired solution. It should always net new gain that you are looking for with a clear focus for documentation.

Defining the larger ecosystem, including processes, location, and organization, that you aim to target for both the current and desired states can be a good starting point. This will help set a boundary for the process and make it easier to define the current and the desired states.

Clarify the project's goals and stakeholders, setting the context for documentation. Define scope by outlining boundaries, constraints, assumptions, and risks. This ensures focused and relevant documentation without unnecessary details.

Even before coming up with the scope and purpose of your project, in most cases, this tends to be a subset system of a bigger system. The bigger system could be defined by the mission, vision, and core values of that organization. A past experience I had working on two projects I encountered showed that without knowing what triggered need ultimately led to mis-specification of scope and purpose. The triggers could be event-driven as my first case was the loss of data, while the second was actualizing a legal act establishing a regulatory framework. Therefore, documenting the nature, and characteristics helps to define the scope, purpose, and terms of reference of what is to be achieved.

Effectively and precisely writing down the objective and goal of the project followed by the document purpose goes in a long way in establishing the requirements

When diving into system documentation, clarity is paramount. Opt for straightforward visuals to unravel complex structures. Focus on the crucial functions and features to steer clear of overwhelming details. Most probably, you'd want your documentation to be a helpful guide rather than an exhaustive encyclopedia. By keeping it engaging and precise, you ensure stakeholders grasp the system's intricacies without unnecessary complexity.

Right-sized documentation is the key. There is never a one-size-fits-all approach that works for documentation. You will need to have different levels of abstract based on the intended audience. Remember to have data flows or sequence diagrams for the technical audience but business process flows for business stakeholders.

Choosing the appropriate format and level of detail for project documentation should be determined after formal stakeholder assessment. A well performed assessment will help identify the differing needs across the organization. Interacting with senior management may require high-level graphical milestone readouts, a shared serviced or compliance function may require detailed reporting that demonstrates effectiveness of planned system features, or a traceability matrix linking requirements to the system project scope. Understanding the specific needs of the stakeholder should drive the level and type of documentation required, relying on industry best practice to define the tools selected for various types of system project documentation

I think that a good practice is to ask specific questions and make models that try to answer them with a limited number of elements and relationships. If you wish to delve into any details, you can prepare models to a next level of detail using a top-down approach. For each detail model, the same practice should be followed: Ask specific questions (in this case, subordinate to the original question)

To keep a Documentatiom up to date is a challenge. Choose a level of doucmentation which you are able to maintain in the future. It's sometimes better to describe a system on a higher level than to go for much details, which will change more often. Detailed documentation is best generated automatically.

The current state assessment is too often a rushed, check-the-box exercise driven by a belief that "we already know what we do, we simply need to focus on the future state". My reaction to that is always, "it's very hard to truly know where your going unless you know where you have been and who you are currently. Focusing on who you are and where you've been (in recent history) should be a fact based exercise that identifies the relevant processes that need to be considered, along with current constraints, handoffs, key inputs / outputs, and key stakeholders. Properly mapping all of these processes and related touchpoints help adequately identify the "pain" or business process gaps that need to change in the future-state model or system.

It's always tempting to do the job as the previous document template. Well, it's gonna be a lot easier that way, but please keep in mind that our job is to deliver the current state documentation for someone in the future. With that in mind, I believe raising the standard will always come as a better choice. Always try to be very very detailed in documentation but keep using simple language so that it is easy for others to understand.

Start from the basics of the business domain. Do not rely on "everyone knows that..." -- it is almost never correct. Different stakeholders may and usually do have different viewpoints, and much more often than not use the same terms to mean different things (synonyms and homonyms exist). This has been known for decades if not centuries. For an overview, see, for example, "Data and Reality" by William Kent.

Examine the existing processes, data, rules, interfaces, and issues when documenting the current state of a system. Employ techniques like interviews, observations, surveys, or document analysis to gather and validate information. Utilize tools such as process maps, data models, and business rules catalogues for documentation and visualization. The objective is to gain insight into the current situation, identifying areas for improvement and potential opportunities.

Identifying the current state of a system involves diverse data collection, inventories, and performance assessments. Interviews, tools, and SWOT analysis uncover issues and opportunities. Considerations for security, compliance, and expert insights enrich the analysis. Detailed documentation, validation, and prioritization guide actionable plans. These best practices enable informed decisions and structured strategies for enhancing system functionality, security, and performance.

Outline and confirm the envisioned outcomes, benefits, and requirements when documenting the desired state of a system. Employ techniques like brainstorming, workshops, prototyping, or use cases to elicit and specify requirements. Utilize tools such as vision statements, benefit maps, requirement specifications, or user stories for documentation and communication. The goal is to articulate the vision, scope, and criteria for the solution, setting the foundation for the desired state.

Defining the desired system state involves setting SMART objectives aligned with organizational goals. Benchmarking, visual aids, and KPIs ensure realistic targets and clear metrics for success. Feasibility assessments validate achievability within resources. Prototyping, iterative feedback, and documentation refine and align the envisioned state with actual needs. Regular reviews and adaptations ensure relevance and continual alignment with evolving circumstances, fostering successful system improvements.

Use the current situation as a base to reach the desired state. Capitalise on SWOT - Strong, Weakness, Opportunities and Threats, to define improvements. Start brainstorming with key Stakeholders to elicit several options. Drive workshops to specify use cases and expectations. Test, qualify and challenge solutions. Compare results with the vision and scope

Start with listing acceptance criteria and request for screens proving end systems succeeded. Human perception and misinterpretations leaves little margin for errors.

Its easy to forget the bigger picture when full force in project delivery. documenting the desired state will establish the if the solutions are fit for purpose

In my role as a cybersecurity awareness manager, I've come to appreciate the intricate nature of effective gap analysis. While standard techniques like gap, impact, and feasibility analyses are fundamental, the real depth of understanding emerges from within an organization's unique dynamics. I've found that leveraging internal data, especially from methods like 1:1 interviews, enriches the analysis with qualitative insights often absent in industry benchmarks. These insights play a pivotal role in meticulously documenting and prioritizing gaps between current and desired states. Here, our proposed solutions are finely attuned to the organization's specific requirements, leading to heightened engagement with vital cybersecurity practices

It is very common for BAs to compare the gaps, and identify potential measures to bridge that gap. It is far less common (often due to time constraints, or org pressure) for the measures to be prioritised, using anything other than a gut feeling. Prioritising the gap mitigation measures allows for an objective analysis of the options, and will lead to the optimal outcome.

One thing ive found is not to underestimate the importance of the gap analysis and the prioritisation to "bridge" the gaps by the right stakeholders.The right needs, opportunities and risks for the solution must be identified up front.

As a Salesforce BA, I update the documentation as I progress through the instruction. For example, once I have the expression of need, I write a macro description of the functionality in the Confluence page. Then, once I've finished the Visio, I update the documentation with the link to the Visio, and so on for the validated UX/UI mock-ups, the impacts until I've finished writing the User Stories, and then I add their links.

Documentation reminds us of the critical details how we did a good job after 2+ weeks when we start to forget as we focus on new challenges. It is basic courtesy to leave “I was here” notes for succeeding support groups.

Effective change control document management is absolutely crucial to hold stakeholders responsible for their areas. Scope creep is one thing that should be aimed to be prevented and strict controls and regular review of documentation with checkpoints will help prevent this.

As a delivery consultant, S&OP's and process documentation was key to on ramping; however, most documentation was not complete or outdated. System process and actual process varied quite extensively. This can lead to scope creep, budget/timeline variances and influence change management. I have found that process mining tools that run in the background can give a second view to how the business is effectively operating. Are goods being received when they leave the line? How long does is take to create a sales order? How long are customers waiting for order information? Documentation + System data can provide key insights to operational efficiencies.

The business case for a systems replacement or upgrade generally contains (at best) high-level benefits, that are often difficult to quantify. By analysing the current and desired states of the system, particularly in the context of impact on business processes, organisations can quantify accurately the business benefits. These should then be fed back into the business case and an assessment should be made on whether it is economic to continue.