Written By Jeff Lofurno
ERP Implementation

Documenting Your Current State Application Architecture

Why your current-state diagram matters, and how to build one that survives contact with reality.

One may think it is a reasonable expectation that at any given point in time, a view or diagram of the current state architecture exists within an IT organization. While this probably (definitely) is a reasonable expectation, the reality is that it is highly likely you will need to at a minimum do some heavy revamping of existing diagrams. You may even have to create a completely new diagram. I once came into a project where this was the case. In the end, I'd built a diagram showing 200+ applications with nearly 700 data flows.

Recently, we published an article on the process for documenting current state processes. Many of the principles are similar, however, having spent a lot of time with both, I have developed distinct approaches I prefer between the two. So today, we will shift our focus to application architectures.

Why This Matters

You can't manage what you can't see.

First, let's talk about why this matters. To start, we will get the obvious reason out of the way: It is quite difficult to manage an enterprise IT ecosystem when there are no existing diagrams of the architecture. How do you validate downstream impacts of your changes to create a test plan? How do you allocate resources? How do you maintain a clear view of your technical debt in order to drive critical decisions? And so on.

From the context of your ERP project, there are also many reasons why you require a clear, real view of your architecture:

  • Clear view of your project's value proposition
  • Identification of technical debt which will be wiped away in your ERP project
  • Enablement to conduct a clear analysis on what applications are staying and going, to drive your plans:
    • Future state integration planning (high dollar impact to projects)
    • System / integration cutover analysis
    • Interim state analysis: if you are conducting a phased go-live, you need a plan for what you will do between phases
    • Framing conversations throughout the project (but especially during discovery) by connecting to current state, when needed (not for replication, but context)

The Process

Read it, then adapt it to your situation.

Now, we will get into the approach I prefer when taking on this work. Read it, then consider your situation and apply as appropriate. You may make changes to suit your need.

  1. Identify the stakeholders that hold the knowledge. It is generally easier to start your discovery with managers because they may not know the low level details, but they will have a global understanding that will help build the overall form of your diagram. This is helpful because it is easier to start your detail work with a high-level picture, than to dive right into it.
  2. Get to baseline. Get your hands on whatever documentation is currently available. Consider even using what you have to produce an initial diagram if possible. Similar to the above, having something people can look at as a reference will help trigger thoughts.
  3. Expect iteration. The following steps will be iterative and repeating as you refine. Don't assume you will only need one session per resource. Your diagram and documentation will evolve. You will also learn things from a stakeholder that you realize impacts another one that you thought you were done with.
    • Hold sessions with the stakeholders to gather information. I prefer to keep these sessions targeted, focusing on groups of systems (eg: if I have 5 systems in an ecosystem, I like to start with focusing on two systems that interact with each other to keep it on a smaller scale). This is where you will mold heavily based on your preference, the situation, and even the personalities of your stakeholders. Keep in mind that through these sessions, you will likely get new names of people you need to work with for more detailed information. Leave no stone unturned.
    • During each session, keep the diagram up and make live updates so people can visualize what you are talking about and ensure you are making updates that align to their expectations. Additionally, as more is documented, the better the sessions will go.
  4. Collect extra information for an inventory (this will require additional sessions). Unless you are only intending to make a very high-level diagram, you only will be able to include so much useful info on the diagram before it becomes difficult to follow. Once you start documenting cadences, triggers, data domains, and more, the diagram gets busy, fast. Avoid this by building an excel inventory where you leverage ID numbers for each line then include more detailed information for each integration. By doing this, the diagram will focus on the visual, while the inventory can provide the detail.
  5. Conduct a final review with all stakeholders together, at once. If you have a very complex diagram, cover the review high or mid-level, then give them homework to review the inventory and confirm accuracy.
  6. Maintenance mode. You may be finished officially but I promise you one thing: you will find out about integrations or even applications that were missed in your original discovery. Immediately get the relevant information for this to ensure it is documented. You may even need a full session if it seems like there may be a full group of integrations missed discussing.

Tips for a Quality Product

Small habits that save you weeks.

Besides following a structured process, there are things you can do to improve your work product and efficiency. Below are a few tips to help you produce a quality product:

  • Decide on the level of detail most appropriate for you before you get started.
  • Minimize text on the visual by leveraging color-coding and shapes with legends, as well as reserving deeper info for your inventory.
  • No matter how long you think this will take, multiply by at least 5. Yes, really.
  • Be patient, but assertive. This document will be attached to your name and likely used for high impact decisions. You own it. Do it right. If something doesn't make sense or seems missing, dig into it.
  • Be willing to iterate on the format as you learn more. Don't try to fit it in a format that no longer makes sense. The longer you wait to make the change, the more time it will take.

The Payoff

You'll become the SME whether you meant to or not.

If you follow the defined process and leverage the provided tips, it will be difficult to produce a poor product. Dig in to it and build this valuable IT artifact. You should also prepare yourself to suddenly be the SME on the overall ecosystem, even if you don't happen to have a technical role. That will pay dividends in itself, as you will be able to partake in conversations you otherwise would not have been able to.

Jeff Lofurno
Next