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

#1

Post by dvasdekis » Thu, Nov 22, 2018, 6:32 AM UTC

Despite having the 'architect' title for about five years now, I still sit for hours in Visio & Powerpoint to painstakingly drag boxes and lines around to describe systems.

While the system definitions themselves have arguably improved as my skill as an architect has increased, there's been no such improvement in the speed or method I use to describe them. My visuals are perfunctory, powerpoint-fu is lacking, and the end result always has plenty of room for improvement. It then gets saved as PDF and shelved as an artefact that is disconnected from all the other architectures, and the system boundaries are inevitably out of date by the time the next person looks at it.

So much craft has been put into better languages, better compilers, and better IDEs for the software developer, I'm absolutely confused - where is the modern 'IDE' for the Software Architect?

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

#2

Post by zzzzzzzza » Thu, Nov 22, 2018, 6:51 AM UTC

“Show me your flowcharts (source code), and conceal your tables (domain model), and I shall continue to be mystified; show me your tables (domain model) and I won’t usually need your flowcharts (source code): they’ll be obvious.”

~ Fred Brooks, “The Mythical Man Month”

Stuff that has improved or the potential to improve the documentability of modern systems, imo: postgREST, custom types (e.g. domains in postgresql), more expressive type systems e.g. rust, haskell, typescript perhaps (though I am not completely sold on typescript yet myself) nix/nixos (or more mainstream, hashicorp products/ansible/puppet/docker) kubernetes and co. (most people probably don't need)

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

#3

Post by meh2frdf » Thu, Nov 22, 2018, 7:38 AM UTC

Try using a modelling tool rather than a drawing tool.

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

#4

Post by Msurrow » Thu, Nov 22, 2018, 12:31 PM UTC

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 some point. Qualiware have better publication options than the others, as far as I know, but not completely sure. The Archimate tool probably only supports the Archimate notation standard, where as the others support BPMN, UML, DMN etc. So I’d go for those, unless you are really heavy into TOGAF, then Archimate may make sense.

Edit: these are “big” tools that can do alot of differnet stuff and you wont ever need all of the features in one of them. But also means you need to dedicate some time to learn how to use it (alot more time than you needed to learn PP or Visio)

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

#5

Post by sachin_m » Thu, Nov 22, 2018, 1:51 PM UTC

Try PlantUML. For system architecture, you can check this PlantUML extension https://github.com/RicardoNiepel/C4-PlantUML

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

#6

Post by thedevindevops » Thu, Nov 22, 2018, 3:41 PM UTC

>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 architecture solves the business requirement it pertains to.

It's not something you wash your hands of and walk away from, having handed it over to the dev team. You're in it for the long haul, same as them.

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

#7

Post by Yeaw » Thu, Nov 22, 2018, 4:58 PM UTC

Gaphor (https://github.com/gaphor/gaphor) is an open source UML tool written in Python. The goal is to create a simple, easy to use modeling tool not a big enterprise tool like the ones already mentioned. I would like to soon support SysML which is for modeling systems design and requirements. We are finishing up converting it to Python3 and Gtk+3 now. We would love more involvement or input if there are things you would like to see supported.

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

#8

Post by segmondy » Fri, Nov 23, 2018, 2:19 PM UTC

Pencil & Paper, take a picture scan it in. Then type up descriptions.

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

#9

Post by PopeDotNinja » Sun, Nov 25, 2018, 4:02 PM UTC

sachin_m wrote: post #5

Try PlantUML. For system architecture, you can check this PlantUML extension https://github.com/RicardoNiepel/C4-PlantUML

Plant UML is good. If you find it a bit constricting at times, I believe you can drop DOT graphs into the PlantUML diagrams, too. DOT is the language used by graphviz. You can of course use graphviz directly, too!

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

#10

Post by cimi_ » Sun, Nov 25, 2018, 4:08 PM UTC

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