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

151–160 of 239 posts

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

#151

Post by killjoywashere »

I work in between policy and the actual scientists writing code and running experiments. I use Visio and LucidChart to make sure I've figured out how the decision flow in policy space can map to some realizable version of meat space and network space, and demonstrate to actual policy makers where their policies may not work (e.g. there's a pocket of bureaucrats who we know will squeeze the time out of our clocks, here's some software or infrastructure that will require additional authorization because it exists inside or outside a policy boundary, etc).

Some of those documents I never look at again. Some of those documents I show to other people and it's like watching lightening strike: "Oh, I like this, I like this a lot."

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

#152

Post by flarg »

Msurrow wrote: post #4

Well, you need to use an architecture modelling tool to work [efficiently] with architecture models. Here are some I know of: Sparx’s Enterprice Architect NoMagic’s MagicDraw Qualiware Achimate (the tool, not the standard) There are surely more out there. I know both Sparx and MagicDraw have the possibility to write your own custom plugins for the tool. If you are in a big enough shop that will become very handy at s…

EA is effectively a database of design artifacts, models and components so you can draw different viewpoints of a system and previously defined relationships are automatically displayed. Plantuml, which I love, can't do any of that.

EA also auto generates documentation in Office formats which is handy when submitting a design for review and comment.

A lot of other commentators will point out that UML is redundant, but in big enterprise system development it is still a useful design tool to start a discussion and not too onerous to keep up to date. Whilst even at enterprise scale you still want to evolve architecture as per Agile best practice, things take a little longer and there are more hoops to jump through and this is where well documented architecture always shines through.

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

#153

Post by p1necone »

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…

Planning is highly useful, plans are useless.

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

#154

Post by artwr »

avip wrote: post #91
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.

Ha-ha, the joke is on you, the systems I have inherited do not have tests.

Joke aside, tests are a great resource when they are present. The other technique I have used was to look at the system like a black box, and only look at the expected behavior at the boundary. Sometimes, it is the fastest way to clear old cruft.

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

#155

Post by mattdeboard »

TylerJewell wrote: post #36
thedevindevops wrote: post #6

>where is the modern 'IDE' for the Software Architect It's the same one the software developers use, 'architects' don't stop coding, the system architecture doesn't exist in Visio or PP. It's evident from the structure of the codebase and the accompanying documentation, your role is to collaborate and work with the senior devs to ensure this design vision is realised and to explain in documentation why this architect…

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 addressing the idea of understanding code through diagramming. I am _much_ more interested in understanding complex infrastructure through diagrams. What queues do we have, what are the producers, what are the consumers? Where is the database? What writes to it? What do we shard on?

Code's a lot slipperier to autodoc, and the slipperiness is a function of number of contributors.

Infrastructure, however, we have been herding (pun intended) to a more declarative, predictable paradigm for years which is great. So let's start building the auto-documentation stuff into e.g. Terraform, since infrastructure-as-code seems like the natural place for such useful side effects of provisioning assets.

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

#156

Post by AdieuToLogic »

user5994461 wrote: post #15

Dia/visio for general diagrams and ArgoUML/plantUML for sequence diagrams. I found that the only useful UML diagram is the sequence diagram, that really needs a dedicated tool to draw. PlantUML has simple text markup to describe diagram. It's easier than drawing and it can be integrated in documentation and generated on the fly (sphinx, wiki, doxygen). And last but not least, ascii diagrams with http://asciiflow.com/…

+1 for ArgoUML. It's been a solid modelling tool in my experience. By using it for capturing key abstractions and avoiding code generation/reverse engineering diagrams, keeping the diagrams up to date is made easier.

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

#157

Post by vruiz »

taeric wrote: post #52
jonathanlydall wrote: post #39

Full disclosure: I am one of the developers of a product which does the below, also known as model driven architecture. For about 5 years now, the teams I have been on have found great success in the use of DDD. Towards this we have used a tool which not only allows us to visually model the domain using UML, but also performs what we call “code management” (smarter code-gen which doesn’t get in your way, or produce u…

If the code is generated from the diagrams, why check the code in at all? Feels akin to checking in the bytecode with your the java that generated it.

Speaking as someone who checks in other kinds of generated code. The tool, like any software, can have bugs/changes in behavior across versions. You don't want to introduce the chance of that happening without being audited in version control if you can easily avoid it.

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

#158

Post by derangedHorse »

rocqua wrote: post #115
taeric wrote: post #52

Earlier quoted context omitted.

If the code is generated from the diagrams, why check the code in at all? Feels akin to checking in the bytecode with your the java that generated it.

I can envision two reasons. The first is that, in truth, the code generated from the UML, isn't good enough and people still actually work on the output. The second guess is that humans occasionally rewrite the code for optimization. It might then be easier to source controll the code rather than patches.

There's also the reason of not wanting to generate all the code every single time someone new retrieves the repo or needs to revert back to a previous commit.

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

#159

Post by fzaninotto »

I developed an interactive visualization just for that purpose a few years ago. It's called ArchitectureTree.

https://github.com/marmelab/ArchitectureTree

The tech stack is a bit outdated (it used Angular.js), but the idea (using JSON to store the architecture) and the UI (powerful search, "bush" look) are still a good answer to the requirement of vizualizing complex software architecture.

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

#160

Post by derangedHorse »

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.

As someone who's been in software development for only a couple years by comparison, I don't see huge architectural changes happen too often for any of our products. This is something that I'm currently trying to improve upon within my company, but I've gotten pretty discouraged with all these comments lol. Is there any way to mitigate the obsoletion of these models?
Post reply on HN