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

181–190 of 239 posts

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

#181

Post by zeroname »

pojzon wrote: post #168
luckydata wrote: post #167

Earlier quoted context omitted.

I would use them if they existed. I usually spend the first couple months of my tenure with a new team documenting the product after I ask a few questions and inevitably people start giving me answers that are rarely consistent. After those diagrams are created, usually everyone is SHOCKED that discussing the system becomes so much easier. Unfortunately, modern software teams don't value documentation and that's the…

"WORKING PRODUCT, over comprehensive documentation" Software changes too fast to make a static snapshot of it. Its the same with comments in the code, few months later what was there is no longer valid and only creates confusion. But i can understand managers dont like that because it makes it harder to replace ppl.

> Software changes too fast to make a static snapshot of it.

Architectures don't really change that fast or often, except maybe in the initial phase. That's why most UML diagrams are a waste, they are concerned with low-level details like classes or internal interfaces.

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

#182

Post by WaxProlix »

I had an idea and made a proof of concept for a framework based on ontology language that generated both cloud resources (AWS cloud formation, with the plan to target similar infrastructure description languages) as well as a set of code snippets for CRUD operations to be deployed to those resources. The nice part was that you'd have all your types and data flow modeled in a source-controlled set of repos, and you could generate and publish up-to-date system diagrams at any level of granularity you wanted. Seemed cool but I never got around to doing much with it.

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

#183

Post by zeroname »

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

> But my domain model is...

No it isn't. That's the model for the representation of the actual domain model. The actual domain model may well be "idk everything" (then you're SOL) or it just may not be formalized (then you might want to fix that).

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

#184

Post by azhenley »

zanny wrote: post #171
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.

What would be useful is the ability to generate diagrams like UML from an AST. I'm sure theres already a Rust crate for it out there somewhere... Then it could just be the case where you pick out a root struct / mod / something and a depth and let the software generate you a pretty graph to stick on a slide for the meeting in 15.

A lot of tools exist for generating UML from code (and some for generating code from UML).

I've never found any of the generated UML to be helpful (too big, too many details, and too much effort for me to simplify). Funny enough, Visual Studio cut out the builtin UML designer from VS 2017.

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

#186

Post by teyc »

I like Arc42. It is aimed at documenting technical architectural decisions, the whys and constraints (budgetary et c) that lead to a particular design.

It also outlines the main boundaries, the key interactions.

Architecture should not be about the details. Rather it should be like a guide so that the developer can look at the source and see for themselves.

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

#187

Post by hyperpallium »

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…

Yes.

- But is "out-of-date" the problem? "round-trip" UML tools, auto-generating UML from code, seemed like a great idea once (e.g. Rational, Together), auto-keeping UML up-to-date. They don't seem popular now.

- Is UML the problem? (IMHO: no. It's good enough to be useful; like, no matter how bad XML is, it does work).

- Or is it that the devil is in the details, and you just can't summarize code?

IMHO, docs of architecture would be the most useful of all docs. Design patterns, javadoc-like tools, type-systems and UML all try it.

In the end, understanding the domain problem is the key to understanding the solution approach, which is key to understanding its architecture. That's a lotta understanding.

In practice, I inspect source, stepping through manually - your way's better.

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

#188

Post by pron »

ex_amazon_sde wrote: post #61
agentultra wrote: post #58

You can use TLA+ -- it's what Amazon and Microsoft uses. TLA+ is a formal specification language, plain-old maths, and the tool suite includes a model checker and a pretty printer. The model checker verifies properties of your specification that you want to hold true such as liveness. And it also includes a pretty-printer for exporting your specifications into well-formatted PDF documentation. The nice thing about wr…

> 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.

> TLA+ is very useful but only few services adopt and benefit from it.

It's true that formal specifications are rarely used, but I would bet that the ratio of those that benefit significantly from them to those that use them is far greater than many other, far vaguer tools.

> Also it's not very readable

That depends on what you mean by "readable." A prose description can appear readable in the sense that the reader may think they understand what the document says, but sometimes that's just because the text is vague enough to allow for conflicting interpretations. TLA+, on the other hand, is precise. True, it takes some learning, but it's easier to learn than a programming language, as it's much, much smaller (the reference documentation for the entire language and all of the standard library fits comfortably on 7 pages (https://lamport.azurewebsites.net/tla/summary.pdf)

> and cannot document many design aspects e.g. the reasons behind technical decisions

It can document some decisions very well. For one, you can state precisely your assumptions as well as the requirement. You then describe the desired operation of the system. You can then check that the design fits the requirements given the assumptions, and show that other designs don't. It is true that it's not intended to model the reasoning behind every decision, such as cost/time of implementation, but generic (i.e., non-software-specific) project management tools can help you with that.

Now, I am not saying that a formal specification is always required, and I agree that writing down an informal one is far better than not writing down anything at all, but it can really save a lot of time and trouble in subtle/complex/unclear cases.

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

#189

Post by pron »

qznc wrote: post #98
agentultra wrote: post #72

Earlier quoted context omitted.

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/

It makes a lot of sense for 1, 2, 3, 6, 7 and 12.

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

#190

Post by royalghost »

After the System Design Primer by Donne Martin got quite popular on Hacker News, I contacted Donne to find out which tools he used to draw those system architecture diagram and he was kind to respond my twitter message ( that is why twitter is so great ) to tell me it it is Omnigraffle ( only available in Mac and ios. )

10 years back I used to draw UML diagrams using Visio or one of the eclipse plugins for building systems diagram. However, the software landscape has changed quite a bit. On one of the podcasts of Martin Fowler recently, he also agreed that UML is now less favored standard in the software community.

Although I use Windows on my work but for the demo of the product I was working I built the system architecture diagram using my personal mac book and transfer to my work laptop to made a presentation. There was a good feedback and no-one raised any concern with UML or (any-)standards.

So, tool or IDE is less important these days, as we tend to use multiple tools/IDE based on the technology / framework / programming languages. I use intelliJ for Java, Sublime for Ruby / Rails + Angular + Others, Visual Studio for NodeJS, Vim for scripting, etc. etc....

Post reply on HN