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

131–140 of 239 posts

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

#131

Post by PopeDotNinja »

henrik_w wrote: post #96
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…

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

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

#132

Post by ghthor »

perssontm wrote: post #117
taeric wrote: post #92

This is a loaded question. Is there a better way? Maybe. It is almost certainly not any easier, though. Likely takes longer and requires as much investment from the reviewers as it does from the authors. I confess I'm fond of Literate Programming for this, though, I have never tried introducing it in a company. My hunch is it would take too long. By far. Even documented software often takes too long. Same reason you…

I've long dremead of a architecture view that was zoomable, zooming in enough would end up on the actual code, but zooming out a lot would show you app server +database basically.

I too have had this dream. It's like a Realtime stragedy game, you have a minimap where you make big movements around the map, zooming in to perform some micromanagement on individual units. Zooming in further to directly edit there AI.

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

#134

Post by cs02rm0 »

henrik_w wrote: post #96
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…

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.

Just 15 years here. I've worked at somewhere where they did put a lot of emphasis on UML diagrams.

To the point they had a product where some of the code was generated from UML, not once moving from the initial design to code, but repeatedly every time the design became out of date. It became the project everyone tried to get away from and project all new joiners were thrown into the deep end on, many quitting as a result.

A couple of years ago I interviewed for a contract role with a sister company and they waxed lyrical about their love of "best practice" UML in the interview. I declined the offer, I'm too old for worrying about which arrow type to use when no one reading it's going to understand the significance anyway. I think there are a lot of attempts to move away from code because it's complex, but the bottom line is it's the best we have for now.

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

#135

Post by gianouts »

I have found that a modelling tool (such as Sparx Enterprise Architect or Archi) as opposed to a drawing tool is useful. With a modelling tool there are increased opportunities for reuse and for the information to be presented in different ways (with differing levels of detail) depending on what needs to be communicated. It's not ideal, but I do however often still use both Visio and Powerpoint to better communicate the information in a more visual manner.

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

#136

Post by rco8786 »

quickthrower2 wrote: post #116
platz wrote: post #99

Earlier quoted context omitted.

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

Looks like a schema to allow the code to decide the real schema at runtime. A poor mans mongodb.

This is pretty common looking for things like CRMs or CMSes where customer specific custom fields rule the day.

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

#137

Post by sagichmal »

agentultra wrote: post #72
ex_amazon_sde wrote: post #61

Earlier quoted context omitted.

> it's what Amazon and Microsoft uses That's not true. TLA+ is very useful but only few services adopt and benefit from it. Also it's not very readable and cannot document many design aspects e.g. the reasons behind technical decisions.

Ok, some teams at Amazon: https://lamport.azurewebsites.net/tla/formal-methods-amazon.... Also it's not very readable and cannot document many design aspects e.g. the reasons behind technical decisions. Not very readable? How so? I'd rather read a concise mathematical definition rather than three pages of prose and diagrams. It is most definitely readable although it does require some training to understand the mathe…

> Not very readable? How so? I'd rather read a concise mathematical definition rather than three pages of prose and diagrams. It is most definitely readable although it does require some training to understand the mathematics if you're not used to reading it. Just as reading a blueprint requires a bit of training.

You glibly toss off "a bit of training" as if it's an afternoon's work over a cup of coffee. Understanding, intuitively, the systems that mathematical models like TLA describe is _extraordinarily_ difficult. Reading that 1-page model description for comprehension could be the work of days. Reading a 10-page prose and illustration description of the same system is likely to be the work of 10 minutes, and result in a much more thorough practical understanding of the system.

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

#138

Post by insomniacity »

tomkwong wrote: post #78
solatic wrote: post #55

If you're on AWS, consider CloudCraft. https://cloudcraft.co/ Disclaimer: not affiliated with and cannot vouch for them. I just think they look cool.

Looks interesting. Anyone used it before and can share the experience? It seems to fill a gap nicely. When there are more than a few apps up in AWS it’s easy to lose track.

If you use infrastructure-as-code like Terraform or Cloudformation you will find it harder to lose track, because the design, and hopefully some comments, are checked into source control.

Cloudcraft is good too, but not the whole answer.

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

#139

Post by mattlondon »

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…

UML Sequence diagrams are useful, if they are kept up to date and reflect reality. I find they are great for the initial "what the hell is this doing?" stage of coming to something new.

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

#140

Post by insomniacity »

perssontm wrote: post #117
taeric wrote: post #92

This is a loaded question. Is there a better way? Maybe. It is almost certainly not any easier, though. Likely takes longer and requires as much investment from the reviewers as it does from the authors. I confess I'm fond of Literate Programming for this, though, I have never tried introducing it in a company. My hunch is it would take too long. By far. Even documented software often takes too long. Same reason you…

I've long dremead of a architecture view that was zoomable, zooming in enough would end up on the actual code, but zooming out a lot would show you app server +database basically.

This would be incredible. No reason zooming out can't also show you stuff like load-balancers, message queues, firewalls, and their config/infrastructure code.
Post reply on HN