C4-PlantUML VS Sourcetrail

C4-PlantUML: Export your model as C4-PlantUML diagrams.

PlantUML + C4 plugin;

Yes. I use this all the time for software diagramming. With c4 model (https://github.com/plantuml-stdlib/C4-PlantUML) and AWS icons (https://github.com/awslabs/aws-icons-for-plantuml)

The C4 model (https://c4model.com/) is great for architecture diagrams. You can use different tools to generate them. Here are the ones I've been using:

- https://github.com/plantuml-stdlib/C4-PlantUML

3️⃣ Text-based diagramming- C4-PlantUML

> onboarding docs

yes, they're don't changing frequently

> system design docs

yes - see C4-PlantUML[1]

> meeting notes

no, unless they're directly code related like ADRs [2,3].

Although one can abuse Github Issues + comments for this, in my opinion it's better to use modern SaaS tools for this, i.e. Loom, Descript, Linear.app, etc. - you can automate this process, e.g. transcribe the meeting's recording and add the issue/repo using Github Actions.

--

[1] https://github.com/plantuml-stdlib/C4-PlantUML

[2] https://adr.github.io/

[3] https://docs.aws.amazon.com/prescriptive-guidance/latest/arc...

I use a combination of: * Markdown (for notes and code blocks) * Mermaid markdown (for architectural diagrams in markdown documents) * PlantUML markdown (again for arch. docs in markdown, but mainly for C4 diagrams) * a Docker container to render PlantUML markdown to images * Joplin, installed on every device I regularly use * NextCloud, to store, secure, encrypt, and make available everywhere, the markdown notes managed by Joplin

I wish something existed in this space. I used Coati Software's Sourcetrail for a couple of years. Unfortunately it was discontinued. It was a wonderful piece of software that indexed a code repository, and exposed an interface to explore it interactively. At least for me, it significantly improved the understanding and legibility of code.

The code is in an archived state (https://github.com/CoatiSoftware/Sourcetrail). Searching for the software on Google shows some screenshots.

I think it might make large scale code visualization in a similar way to how SourceTrail does it more feasible: https://github.com/CoatiSoftware/Sourcetrail

Yep souecetrail https://github.com/CoatiSoftware/Sourcetrail

Sourcetrail?

You could always try using Sourcetrail. Unfortunately the open source project is now archived but it should still help you get insights into your code.

Sourcetrail actually tried to do that for a select few languages https://github.com/CoatiSoftware/Sourcetrail

Sadly, they retired the entire project a while back.

> So, is it a good idea to try documenting the code design through some sort of visualization?

Yes, if it helps you understand how it works and how the pieces fit together.

No, if the previous is not all that useful for you (different types of learners), or you need to spend significant amounts of time doing it manually, especially given that code could change.

If you can, look into any tool that might allow you to get visualizations in an automated manner.

For example, JetBrains IDEs have a few different graph visualizations for dependencies and inheritance etc.: https://www.jetbrains.com/help/idea/2022.1/tests-in-ide.html...

There also used to be SourceTrail, though sadly the project is now retired: https://github.com/CoatiSoftware/Sourcetrail

For databases, you can also use external tools like DbVis: https://www.dbvis.com/features/

There are also a few tools here and there for visualizing networks or how container deployments look, but those are pretty situational/specific for each platform/setup.