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?
Top comments (11)
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.
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.
Can't agree more!
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.
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.
I definitely agree that an architectural diagram can be more valuable than pages and pages of textual documentation, particularly for giving that at-a-glance overview. "A picture is worth a thousand words"
I'm a bit sceptical about automatically generated diagrams, or rather I know that they're great as far as they go but... I guess I'm thinking of complex systems with separate components in different code repos, and different layers of across a tech stack. To get a good overview diagram of something like that, you kinda have to draw it yourself. Why? Because it would be difficult/impossible for a diagram generator to infer information across all those things, and also because a diagram of a complex system requires some manual decisions and perhaps even a little artistic flair, in choosing what details to leave out!
But of course a manually drawn diagram is something which then needs to be maintained.
What software do you use to automatically make architectural diagrams?
sourcespy.com/