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

161–170 of 239 posts

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

#161

Post by mden »

basdp wrote: post #123
bdittmer wrote: post #81

Earlier quoted context omitted.

“Try moving towards architectures like micro services. KISS.” I don’t think you have worked with micro services, or more importantly have had to manage them.

All the time.

My initial impression is the same as the parent. Juxtaposing microservices and KISS seems weird as the "architectural complexity" of microservices is several times higher than a monolith. You're not only multiplying the points of failure but also increasing the difficulty of translating the domain into code, especially when it comes to reading and writing from a db in a safe and efficient manner. Someone will need to come up with an answer to handling transactional operations that span multiple services sooner or later (or I guess the team can just accept some small percent of data corruption, which is what I'm guessing most companies that do microservices actually do, willingly or unwillingly). Ironically I think the benefit of an architect is a lot more evident in a microservice architecture than a monolith.

Edit: though maybe my view on what an architect should do is different? I think of a software architect as the person that lays out the skeleton and foundations of a project and has the answers to hard questions. Very likely someone who actively codes or has solved very similar challenges to the ones being solved.

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

#162

Post by hartror »

elviejo79 wrote: post #89

Currently my Favorite tool to Diagram Sofware Architectures is the C4-Model [1]. For the static view and use a normal Sequence Diagram for the Dynamic View. In both cases I like to use Plant UML, so that the text get's converted to the diagram[2]. That way the diagram can be stored together with the code. [1] https://www.infoq.com/articles/C4-architecture-model [2] http://plantuml.com/sequence-diagram

C4 is my goto as well.

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

#163

Post by ryanSrich »

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…

In certain cases they are required. For example - compliance audits of varying flavor require architecture diagrams. To be clear, I expect that auditors understand less than 1% of what they look at in a diagram or why certain systems look the way they do, but it is a requirement none the less.

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

#164

Post by gdw2 »

cimi_ wrote: post #10

The Art of Visualising Software Architecture by Simon Brown is an interesting presentation on this topic: https://www.youtube.com/watch?v=zcmU-OE452k He references this other talk by Adam Tornhill on a similar topic: https://www.youtube.com/watch?v=XzsXvsHcjc0

Along with this, Simon has developed Structurizr, which uses code to describe architecture and then visualize it at different levels:

https://structurizr.com/

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

#165

Post by sien »

mattdeboard wrote: post #155
TylerJewell wrote: post #36

Earlier quoted context omitted.

The Ballerina programming language (ballerina.io) has a syntax designed in such a way that any syntactically correct program can have its sequence diagram generated automatically. It's a type of self-documenting programming language. It only documents for the scope of the service that is being programmed, but eventually if many components and services are programmed with Ballerina, system wide architecture diagrams c…

This is interesting. I ctrl-f'd for "self-doc" because I was wondering when we will start seeing Terraform, Puppet, etc., have options to generate a diagram automatically as part of their normal operation. Self-documenting infrastructure would be a godsend. My organization is challenged by the lack of documentation of our infrastructure, especially. edit: Most of the responses to the original post seem to be addressi…

It's already there with Terraform but it's not that pretty yet:

https://www.terraform.io/docs/commands/graph.html

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

#166

Post by afarrell »

I wonder how useful it might be to try sketching cartoon technical explanations of the type that Julia Evans or Lin Clark do. Then again, how long does it take to develop the manual skill to produce these?

http://jvns.ca/zines/

https://code-cartoons.com/

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

#167

Post by luckydata »

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 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 source of a lot of miscommunication, slowdowns and frustration.

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

#168

Post by pojzon »

luckydata wrote: post #167
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 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.

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

#169

Post by shay_ker »

This reminds me of an idea I had: building service maps from logs.

If your logs have:

1) common format

2) service application names

3) tracer bullets

Then in theory it should be possible to create a crude visualization of a service mesh across your apps. It'd be a lightweight version (or extension) of Zipkin, I think. Although I'm sure there's a bunch of edge cases I'm not thinking of.

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

#170

Post by vkaku »

Suggestion: There is none.

Start writing a blog in Git using Markdown and some basic images (export diagram as PNG). Use HTML where necessary, for instance, tables.

Use dotty/sphinx/doxygen for autogenerated stuff. If your architecture changes too often, you are doing something terribly wrong.

Do not worry about extraneous things such as mobile form factor, jazzy visuals, image DPI or things like that. Instead, focus on making the text more readable or the diagrams easier to understand.

If you want to not be disconnected, write/use a relatively simple script to export a document as PDF (RelaxedJS or Prince).

Post reply on HN