I get to work with some of the smartest engineers on some of the most interesting projects. However, every time I join a new team and ask for an overview or ask for something to be explained I am handed documents adding up to 10s to 100s of pages and sometimes hours of recorded meetings going over the topics. The detail is provided is amazing, but the major problem is that the learning curve is so initially steep to even begin to understand the basics of what you are looking at.
I have developed a general rule that any one topic should be explained in one normal page, meaning at most 500 words to explain a topic. This rule also applies to diagrams, as platform architecture or systems overview should be displayed one page. Diagrams that get bigger than one page become hard for the reader to navigate and understand.
Now we are technical people, we need to be able to dive into detail to understand a topic – the key word here is a topic. If that top level one pager has to make an abstraction, it is perfectly fine to include a linked one page that explains that portion in detail that a reader can dive into if they need clarification.
An example of this would be a business proposal, the one pager on it might give a high level overview of the project, a timeline, and cost and revenue analysis. Each one of the topics covered in this initial one pager, may have a follow on one pager dedicated to just that. The same would applied to an software architecture diagram, the high level one-pager might have a general box that says “Delivery API” and a follow on one pager on just the Delivery API will dive into the micro service layout, databases, caches, and queue involved. Trying to show all of this on the top level diagram may make for a complete diagram, but it becomes challenging to read.
By treating each topic as a one pager that can stand alone, you will make information much more approachable to your audience.