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

71–80 of 239 posts

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

#71

Post by basdp »

Kaveren wrote: post #46
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…

> "There is no value in an architect who doesn’t code" This is debatable. The OP almost certainly knows how to code, and I think you can still provide quite a lot of value even if all you do is architecture. It's much like saying a building's architect is worthless if they're not also doing construction work. I don't buy it.

Buildings are still built using stones, wood, cement. That doesn't change much.

In my experience as a DevOps transformation expert, 'Architects' are mostly old devs that have been kicked upstairs. The whole world changes each year to an extreme. You have to get your feet wet.

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

#72

Post by agentultra »

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.

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 mathematics if you're not used to reading it. Just as reading a blueprint requires a bit of training.

You can write prose into your specifications and integrate the outputted PDF specifications with the rest of your documentation.

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

#73

Post by maccio92 »

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…

What is the tool?

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

#75

Post by basdp »

ex_amazon_sde wrote: post #69
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.

That's nice! Agile to the max!

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

#76

Post by pramodbiligiri »

Wikipedia has page on Architecture Description Languages - https://en.wikipedia.org/wiki/Architecture_description_langu...

I've looked at Wright and Acme that are linked from that page. I came away with the conclusion that you need to use a formal language to describe relationships between the entities in your system. The language should be flexible enough to define new entities, and new kinds of relationships. All of that points to the need for an API/library to describe software architectures, probably using parameterized types in Scala/Java or relying on features in more dynamic languages like Ruby. The language need not be Turing complete, though.

An added benefit of using a formal language is that you can verify whether the invariants of the system are maintained when you make changes. For example: If you try to connect two components which support different protocols, the program won't validate.

These ideas may also have overlap with software specification languages - https://en.wikipedia.org/wiki/Specification_language . I didn't dig too much into that aspect.

Generating diagrams with suitable layouts from this description is a separate problem. Perhaps something from the field of graph drawing could help? https://en.wikipedia.org/wiki/Graph_drawing

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

#77

Post by basdp »

whydoineedthis wrote: post #23
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…

Nice answer! No one else is trying to help this guy turn his life around, they are just answer in his question like sheep. /S

Sometimes the answer to the wrong question helps you further down the wrong path.

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

#78

Post by tomkwong »

solatic wrote: post #55

If you're on AWS, consider CloudCraft. https://cloudcraft.co/ Disclaimer: not affiliated with and cannot vouch for them. I just think they look cool.

Looks interesting. Anyone used it before and can share the experience?

It seems to fill a gap nicely. When there are more than a few apps up in AWS it’s easy to lose track.

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

#80

Post by pmontra »

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"?

In my experience, a multi country mobile operator bootstrapping when 3G was a new thing 15+ years ago.
Post reply on HN