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

61–70 of 239 posts

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

#61

Post by ex_amazon_sde »

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.

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

#63

Post by unixhero »

tokyodude wrote: post #59

What love about the Shinkansen, at least Tokyo Osaka is that it leaves every 5-10 minutes so I never make reservations. I just casually go when I feel like it, shop outside for a snack, then go in and get a ticket at a machine and hop on the next train. This is something I can't do with planes as well as you have to book in advance, get there early, check in, get inspected, line up to board. Filling plane seems to ta…

Wrong thread mate

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

#64

Post by narrator »

Use mediawiki, the software that runs Wikipedia, to document. It doesn't easily go into book format, but hypertext is really powerful and easy to use. You can also embed powerpoints in it. Best of all, updates and versioning are easy as it's a living breathing hyperlinkable system with a full change history built in.

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

#65

Post by rch »

I've found that writing pseudocode with doxygen formatted comments to generate sharable diagrams is generally sufficient.

I actually got into that habit back when I was working with the insanely expensive suite of Rational IDEs. At that point, and later with the Eclipse Modeling Framework, the goal was to generate code from diagrams.... but that took more work than it was worth in my opinion.

With those tools, or with doxygen, you can get pretty far writing skeleton classes and method stubs, with exogenous systems represented the way you might mock them. Then just drop the generated SVGs into your slides, and profit.

This also answers your question about the lack of tooling: whenever a promising architecture/modeling product shows up they get acquired and then just fade away.

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

#67

Post by unixhero »

fsloth wrote: post #44
pmontra wrote: post #34

Earlier quoted context omitted.

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.

What is "very large"?

1 billion dollar 5 year multi project it transformations

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

#68

Post by ilikerashers »

m-i-l wrote: post #56
ilikerashers wrote: post #38

Earlier quoted context omitted.

Scan up and down this thread. Comments are saying he/she shouldn't have a job, he/she should be writing code instead, who is h/shee to dictate to delivery teams. This was posted a few weeks back by a DRI in Stripe, https://hyperbo.la/w/aws-org-chart/ , which sounds alot like what traditional architects do. Nobody showed any interest. Anytime I've attempted to raise a discussion on this it gets shut down quickly. Yeap…

The analogy I sometimes use is that you don't need an architect to design a garden shed, but you do for a house which is much larger, has complex integrations with plumbing, electrics etc., plus building regulations to comply with, etc. A lot of dev work, especially in smaller companies, is building garden sheds, i.e. small single purpose self contained apps, but that doesn't mean every building is a garden shed.

I like that. The logic is often "I worked on a team that didn't require an architect, therefore no teams require architects".

I do readily admit there are quite a few hapless architects out there though.

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

#69

Post by ex_amazon_sde »

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…

One thing I loved about Amazon was having no architects, visio, powerpoints, UML in any of the teams I worked in.

Each service is designed, documented, implemented, deployed, maintained and advertised to other teams by the same few engineers.

Most documentation and runbooks are just text in wikis. If your service cannot be documented without drawing 10 boxes and 20 arrows you should split it in smaller services.

Post reply on HN