Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Is there a better way to document complex software architectures?

news.ycombinator.com

Post reply on HN
Print view View original

141–150 of 239 posts

Re: Ask HN: Is there a better way to document complex software architectures?

#141

Post by trading_wheels »

PopeDotNinja wrote: post #131
henrik_w wrote: post #96

Earlier quoted context omitted.

I've been developing software professionally for 25 years. I've never found them to be useful. Even if you have them, they're usually out of date, and anyway they don't really help answering the questions you have. None of the places I have worked at have put a lot of emphasis on UML diagrams.

I tend to write up (not necessarily formal UML) diagrams in 2 cases: 1. I'm brainstorming with myself about how I want the software to behave 2. The software is basically done & tested, it's unlikely to change, and communicating the behavior to other people is of value, especially when describing a system that spans multiple components

I'll add (3) When I'm learning a new system, especially if it's big and/or old.

The idea is that if I go to the trouble to document it then the next person won't have to; this is seldom the case because as stated above the get out of date so fast. It's still a great way to learn and confirm your understanding though.

Re: Ask HN: Is there a better way to document complex software architectures?

#142

Post by trading_wheels »

pvorb wrote: post #108
avip wrote: post #91

Earlier quoted context omitted.

It's pretty straightforward - if it's pdf it's not versioned. If it's not versioned it's a fossil. The only thing I've ever done to reason about a new system is read the tests.

I second that. Reading tests is often more efficient than trying to learn about a system through documentation.

maybe - but the codethat's the hardest to understand (age, size, immature) is often the least tested, or worse the tests have been gamed over time because the previous assumptions are no longer relvevant & the code has changed so much new developers just want them to pass.

related aside - In my experience developers are much more likely to cut out old code than they are to remove or refactor irrelevant tests

Re: Ask HN: Is there a better way to document complex software architectures?

#143

Post by trading_wheels »

jordache wrote: post #104
cubano wrote: post #87

Quick question that I only ask because of my 30-odd year history as a corporate contractor... Does anyone here really use those UML-based docs to actually learn the systems? Or do they do what I always did and use the trusty step-debugger for a few days and come up with your own mental model of them? Inevitably, unless someone is working full time on them, they are incomplete and several months out-of-date, and that…

They are useful in articulating high-level insight on how systems integrate together. A well done diagram would have an as of date, and some commentary along side boxes.

>> A well done diagram would have an as of date

maybe we should promote a "best before" date for technical artifacts...

Re: Ask HN: Is there a better way to document complex software architectures?

#144

Post by ChrisCinelli »

cubano wrote: post #87

Quick question that I only ask because of my 30-odd year history as a corporate contractor... Does anyone here really use those UML-based docs to actually learn the systems? Or do they do what I always did and use the trusty step-debugger for a few days and come up with your own mental model of them? Inevitably, unless someone is working full time on them, they are incomplete and several months out-of-date, and that…

Completely agree. Systems change, people that work on them change. A diagram gets obsolete very quickly.

A diagram is mostly valuable in the design phase for me and to have faster less ambiguous discussion with people.

In the systems that do not drastically change, it is sometimes useful later to understand how the system was initially designed by new people.

But for specific part of the system I always have to look into the code on source control. Git blame and diffing commits have become the only good tool able to tell me what I need and also help me to realize what changed overtime, by who and when.

I remember seeing some version control tools for diagrams but unfortunately unless the design is updated as the code gets updated, these tools are worthless.

Comments that are in the code get outdated. There is little hope with diagrams.

The exceptions are tools that get their data from the system. In a company I was working long time ago, we had a GUI to connect parts of the systems. The changes in the UI became real changes in the system. That data was always updated.

For MySQL databases in the past I used a tool that was able to create the table diagram from the schema in MySQL but I had to spend quite some time to rearrange the tables with drag and drop. It worked of if people defined foreign keys and kept the naming consist.

Re: Ask HN: Is there a better way to document complex software architectures?

#145

Post by joe_the_user »

I've never been a system architect. But this reminds me of the principles of comments.

Obviously, one principle is "use as few comments as possible but no fewer".

But another principle is "don't spend extra-time formatting or otherwise prettifying a comment". Not only is that time not spent on development but it makes the comment seem more credible than it deserves and it can make other programmer looking at the comment hesitate to change it when they otherwise should.

Like comments, architecture draws may be fated to be often out-of-date. Like comments, that doesn't mean they're useless. Like comment architecture draws probably actually benefit from not looking more integrated into code than they actually are. They're a starting point, you have to read the code still but a starting point can be very important.

Perhaps your only real problem is finding a draw program you can use faster.

Re: Ask HN: Is there a better way to document complex software architectures?

#148

Post by c_hackett »

> "I still sit for hours in Visio & Powerpoint to painstakingly drag boxes and lines around to describe systems."

I much prefer to skip the painstaking messing with Visio and instead use tools like https://www.websequencediagrams.com

Simple to update and no faffing around with formatting.

I normally then do a screen/audio recording whilst talking about the diagram. These have received very positive feedback from developers and non-developers.

Re: Ask HN: Is there a better way to document complex software architectures?

#149

Post by amelius »

zzzzzzzza wrote: post #2

“Show me your flowcharts (source code), and conceal your tables (domain model), and I shall continue to be mystified; show me your tables (domain model) and I won’t usually need your flowcharts (source code): they’ll be obvious.” ~ Fred Brooks, “The Mythical Man Month” Stuff that has improved or the potential to improve the documentability of modern systems, imo: postgREST, custom types (e.g. domains in postgresql),…

Also as a user! User documentation should imho explain what are the datastructures that a piece of software is manipulating, and what the dependencies between them are.

The rest of the UI, I can figure out by myself.

Re: Ask HN: Is there a better way to document complex software architectures?

#150

Post by 6nf »

platz wrote: post #99
zzzzzzzza wrote: post #2

“Show me your flowcharts (source code), and conceal your tables (domain model), and I shall continue to be mystified; show me your tables (domain model) and I won’t usually need your flowcharts (source code): they’ll be obvious.” ~ Fred Brooks, “The Mythical Man Month” Stuff that has improved or the potential to improve the documentability of modern systems, imo: postgREST, custom types (e.g. domains in postgresql),…

But my domain model is Store ===== Id int Col1 varchar Col2 varchar Col3 varchar ... Col134 varchar foreignKey1 varchar foreignKey1Type varchar foreignKey2 varchar foreignKey2Type varchar ... foreignKey10 varchar foreignKey10Type varchar validFrom varchar validTo varchar isActive boolean deleted boolean

I don't need your flowcharts, I'll be heading for the door!
Post reply on HN