When I have trouble juggling a complicated system in my head, I like to visualize it as documentation. Thanks to automated documentation generators it’s possib

When I have trouble juggling a complicated system in my head, I like to visualize it as documentation. Thanks to automated documentation generators it’s possible to document various units directly in the code, but it doesn’t replace tying it all together in a cohesive knowledge base, nicely formatted in HTML. (There’s tooling that helps with that, too.) To me, writing and updating how-tos, references, glossaries, organizing it in sections is a methodical activity that produces useful questions and helps me understand not just the responsibilities of different units do but also general background and the larger picture, while producing a concrete deliverable useful to future maintainers and operators as a side effect. Illustrations can also be useful to include. There isn’t a one-size-fits-all approach and it really depends on what you are trying to illustrate—a high-level architectural overview may warrant a data flow or component dependency diagram, while a complicated communication between threads might call for a timeline view. (Again, thinking in terms of documentation is useful—consider future readers and future maintainers, what they would want to learn and how much of a pain would it be for them to update.) I believe illustrations don’t work as well on lower levels though like individual code units. If a higher level diagram is not enough and you come up with one that has to change every time implementation changes, perhaps somewhere there’s coupling that could be loosened and cohesion that could be tightened. (That, or I might not have worked on sufficiently complex projects.)