Skip to content

Would you trade your project documentation for updated software architecture diagrams?

github logo ・1 min read  

In my previous company, there was a big focus on creating and maintaining documentation around the code, MAINTAINING specifically. It takes enormous amount of time and resources. And yet, it would take a few senior developers or, again, huge amount of time to understand the code. In my current company, mostly what we use is architectural diagrams. There is no time required to create these diagrams, done automatically within seconds. These diagrams updated automatically based on code changes. That takes minimal amount of time to create and maintain technical documentation.

I guess the question is would you prefer pages of written documentation (which most likely is outdated) or software architectural diagrams which you can navigate through. Each object on the diagram is clickable which allows you to drill down to the next level if needed?

twitter logo DISCUSS (10)
markdown guide

In the many project I've been involved in I've never seen developer documentation. Even comments are hard to find. Generally I've been one of the only or the few that produce anything. Even when the project has been millions of lines of code.

I found that the debugger was my best friend in deciphering cryptic code in often ungodly mixes of different languages. Fortunately modern debuggers can handle it.

So I don't really expect it. I've always done without.
I don't find diagrams particularly useful. I can click around in my IDE just as easily.


I'm not a huge fan of external documentation. But I am a huge fan of comments in the code. I don't like this new fad of excluding them.


Honestly we recently switched to kedro and the usefulness of an automated graph that cannot lie to you is priceless. It's also hard to beat the human reasoning of what/why.

Given everything is well named I would go for the diagram when I need to know the internals, and good docs for something that I am using and don't need to know the internals of.


Thank you.Completely agree! Especially regarding accuracy of presented information.


I'd actually say that a documentation is only needed for external api's/interfaces...
A documentation for every single line of code or just every function is just too much. Too much that anyone could make any use of... I actually think that navigating and reading the code should be easy enough to be understood by any developer... If it's not, you should try to code differently.


I agree that you can figure out anything but the question is what amount of time it takes. Developers spend around 60% of time actually writing the code and the rest of the time, it's figuring out the logic and understanding the code.


Separate documentation is a waste of time. What I did and what I would recommend to do is use your project management tooling in combination with your code repository.

For any new features or change Task, you'll want to reference the pull request that matches the change. Now what has happened is that you've linked the task discussion and details to the code changes in your repo (traceability of "documentation" to code).

In your repo you want to document your functions/objects and create tests that make up that pull request as usual, that's the second part of your code documentation.

For a new developer, he/she only needs to search through your project management tool to find the relevant features and he/she can see the relevant code.

This is an organic process that doesn't require "out of band" work from any developer and you've pretty much covered the code documentation that you ever need.

Classic DEV Post from Nov 24 '19

I created the Web Almanac. Ask me anything about the state of the web!

AMA about the Web Almanac and the state of the web.

Santana16 profile image