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

81–90 of 239 posts

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

#81

Post by bdittmer »

basdp wrote: post #13

Man, it seems like you totally lost connection with technology. There is no value in an architect who doesn’t code (none, if you think otherwise you’ve worked too long in enterprises that don’t deliver enough value to stay relevant the coming years). Just use whatever drawing tools you know and draw up your diagrams. Should never take you hours to draw them up. How complex are they? If they take you so long, you prob…

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

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

#82

Post by gaius »

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…

It's not something you wash your hands of and walk away from, having handed it over to the dev team

Unfortunately that is the reality of the vast majority of Enterprise Architects I have ever worked with, writing massive tomes completely disconnected from the actual systems. The could all be fired tomorrow and no one would even notice (in fact one company I worked for did exactly that after too many complaints about them from the devs! And since they sat in their own cordoned off section, really no one did notice until the meeting invites suddenly stopped!).

The only architecture that matters is a living document; for example the CloudFormation or Terraform that actually generates it for real.

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

#85

Post by maxxxxx »

pmontra wrote: post #34
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…

If the project is very large architects don't have time to code. Sometimes they can test something before taking decisions but all the production code is written by somebody else. Their role is more about meeting people and help the organization making the correct decisions.

I am always wary of architects that don't code or at least aren't involved in the whole life time of the project so they have to feel the consequences of their designs. Our IT department is full of "architects" whose designs then get outsourced to India. Either their designs are crap that doesn't survive the first contact with reality or they are so trivial that pretty much anybody could do them. They spend a lot of time in meetings with important people though.

I find it much better to empower the senior devs of different teams to duke it out among them. Maybe the process is not as clean as having some genius architect divine the perfect architecture but it reflects reality much better.

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

#86

Post by qznc »

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…

I agree that the first important step is from drawing to modelling. Having a single model means that all your drawings are (and stay) consistent.

The next step is the integration with the surroundings to keep the architecture model consistent with the code and the requirements. For the code, the usual way is generate code from the model. That is tricky and has a bad reputation because it is hard to get right. For requirements, the question is whether you actually track them (probably no in SaaS/Web environment; probably yes in embedded).

What I'm not sure about: In theory the integration tests should be derived from the software architecture, but I have you to see even ideas for tool support there.

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

#87

Post by cubano »

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 makes them worthless really.

That's my anecdotal evidence against generating them. I'm at least somewhat sure someone has a conflicting story of how UML "saved the day", but it would be so rare to my experience that I would love to hear it.

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

#89

Post by elviejo79 »

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

Post reply on HN