How to document your environment – Understanding your audience

Author: Matthew Parslow

Modern IT Architecture is almost infinitely complex. Documenting and understanding your environment is a never ending task, and is always going to be incomplete. Given this, we need to make sure our limited resources are spent most effectively to communicate the essential items to the relevant people.

Depending on the size and complexity of your organisation, you may have to address the concerns of security, external audit, executive review, customer review, technical team and others (as well as for your own/your teams reference). You may not need to tailor your diagram or documentation for all of these groups, but often you will need 2-3 diagrams of the same system for different audiences.  What you leave off your diagram is possibly more important thana what you put in, You might even spend hours on confirming details that never make the final cut – but ensuring details are correct and that you have the right message is worth it.

We all know that a picture tells a thousand words, but if 800 of those words either aren’t relevant, or can’t be [expected to be] understood by the target audience, you’re going to lose eyeballs and any buy in very quickly. The aim of a diagram is to give the reader the information they need to make a decision as quickly as possible. The vast majority of uses for a diagram are in review meetings where you are hoping for a sign off – This means you need to sell the solution (regardless of the financial nature of the  project). There may be a requirement to revisit some of the design, but a decisions shouldn’t be put off or a hard sell because of the quality of your diagram.

I’ll go through a few of my go-to diagram styles, as well as the audience they would be best suited for and why. Hopefully you can take some ideas from this and improve your visual communication. Don’t
forget also that art matters almost as much as content. If you can use pretty diagrams and logos etc, and align all your entities just right, and make it visually pleasing, you’re going to have a much more enjoyable time creating it, and people are going to engage with it more and pay more attention.

The 1000ft view (C-level / Project review)

This level gives the project gist and shows the major components, particularly any that have a major cost component. Flows should be simplified, and leave out any in depth technical detail or intermediate steps which don’t materially affect the overall design. For example you may not include a file transfer mechanism on this diagram, or middleware (depending on where it is and how it is used). This diagram often may not explicitly show redundancy, but needs to ensure it is communicated.

Detailed network and/or specifications (Security/ implementation team)

This contains information about the technical details – but not the contents of the data. This would include things like protocols, ports, server type. Data type information should include the format, as well as the nature of the data (PII/other requirements). This also may include the rate/amount of data being transferred. Redundancy setups should be explicitly fleshed out in these diagrams. This is typically what would get presented to the clients security/infrastructure team, to allow them to both understand what is being used and how it affects their overall setup and security posture, as well as what changes they need to allow in terms of firewall/setup to allow it to work.

Data Flow (business and data)

This diagram is for data and business teams – this abstracts out the data about the implementation and simply shows the data flow through systems. It may contain additional information about the content of the data, and perhaps the format. It may include additional metadata sucgh as retention period or data classificiation. This allows the business owner to see the flow of information, and data analysts to understand the flow and manage any additional information management requirements.  This diagram (potentially simplified) may also be used in a C-level or project overview context.

Functional (internal use – may expand on details that are omitted in others)

This is for your reference. This diagram will show the server process in the middle that reformats the files with the correct line endings, and the network redirection that is necessary due to the design of your network, and the time shifting data processing due to limited CPU. This sort of thing distracts from the understanding of the overall process, however this is highly dependant on the nature of the project. This would be used for internal audit purposes, as well as rerence for how to fix issues technically. This typically is used for either internal systems, or systems that are interfacing with clients, but run by your business. You may also use one of these with specific implementation details for the project team on a client deployment.

Bonus: Shading for new and existing infrastructure

When changing or adding to existing infrastructure, I find it helpful to use a colour guide to easily differentiate between new and existing infrastructure. This makes it easy for the reader to immediately see the delta.

If you would like to hear more information about how to document your environment, please reach out to us via email at info@tmg100.com or visit our website https://tmg100.com.