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

91–100 of 239 posts

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

#91

Post by avip »

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…

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.

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

#92

Post by taeric »

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 don't plot out how you are going to win a ballgame. Outside of "score more points than you allow", the plans are almost all exploratory and reactive. Solidifying that into a document is dangerously slow.

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

#94

Post by qznc »

pramodbiligiri wrote: post #76

Wikipedia has page on Architecture Description Languages - https://en.wikipedia.org/wiki/Architecture_description_langu... I've looked at Wright and Acme that are linked from that page. I came away with the conclusion that you need to use a formal language to describe relationships between the entities in your system. The language should be flexible enough to define new entities, and new kinds of relationships. All o…

We plan to try Structure101 [0] next year to verify invariants. I would love to see comments from people who have experience with it.

[0] https://structure101.com/

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

#96

Post by henrik_w »

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.

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

#97

Post by klohto »

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'd like to support this statement that I do not remember the last time I used them as well...

Most of the time, they are accompanied by company (or team) specific TLAs that I do not understand, at the time of starting, anyway.

For instance, 1 year ago I joined NXP, which is a HW oriented company. I tried to study the UMLs, which for instance, described how CMSIS packs are delivered and how they are split into DFPs, BSPs and SWPs. At that time I had no idea what the documentation is about and I've rather started incrementally building my mental image of the whole system. Looking at the UMLs now, I understand them, but I can still clearly see that they will only confuse a newcomer.

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

#98

Post by qznc »

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…

Have a look at the Arc42 template [0] which is a generic outline for software architectures. TLA does not make sense for most of the items there.

[0] https://arc42.org/overview/

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

#99

Post by platz »

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

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

#100

Post by toolslive »

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),…

There are exceptions though, where the domain model is trivial, but you will be mystified without the sequence diagrams. Paxos for example has a trivial domain model (a value that's supposed to be kept identical on all nodes in a distributed system) but the consensus algorithm is non-trivial enough that a lot of people claim you should not even try to implement it (and opt for Raft)
Post reply on HN