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

21–30 of 239 posts

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

#21

Post by mlthoughts2018 »

zzzzzzzza wrote: post #2

“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),…

Absolutely this! No matter what the system is, the important part is being able to laser down to any lower levels of abstraction and reason about the specifics there. Higher level abstraction docs are summaries or getting started guides at best.

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

#23

Post by whydoineedthis »

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

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

#25

Post by Hates_ »

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/…

Monodraw is great for ASCII art https://monodraw.helftone.com/

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

#26

Post by AchieveLife »

I like to use DrawExpress when I'm on the go, have an idea, and a phone or tablet.

https://play.google.com/store/apps/details?id=com.drawexpres...

Gestures and drawing shapes are where the big speed improvements come from. Typing is eh since it's a touch screen but a keyboard fixes that.

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

#28

Post by whydoineedthis »

Great question. I too like diagraming and Im going to check out some of these tools.

Do you have any examples of your work? I can publish some of mine later today (have to remove specific details) if interested. I always love comparing and learning from different diagram styles.

I have found that spending a bit of time building some proficiency in Google Slides was well worth it. You have to do it without a real presentation in mind though, as it distracts from learning g the tool. Another big time saver came when I created a template presentation with colors, line weights, fonts and font sizes that were to my liking. The Polish, if you will, that we often don't want to go back and touch once the technicals are on the page.

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

#29

Post by ilikerashers »

You're going to get a fair amount of hate for mentioning the word "architect" here. They go into the same naughty list as manual testers, Scrum masters and release managers! Despite this, they can be very necessary for large orgs.

I've used Ardoq in the past, decent tool. All manual. Sparx EA looks very similar to visio and heavily TOGAF influenced. Both models are tough to create and maintain. A DSL in their own right.

No one really cares about architecture diagrams until they're really needed i.e platform migrations, rewrites, onboarding new staff, better reserve instance pricing. I've seen 6 different development teams all write architecture diagrams differently. All of them out of date and inconsistent.

I do think there is an opportunity here to build something more useful, the difficulty I see is that architecture is quite dependent on perspective. Security sees perimeters and firewalls, development sees microservices and DBs, DevOps see VPCs and networking.

I did come across weave works visualisation tools for Kubernetes that seem impressive and an OpenSource project but haven't had a chance to play with it yet.

You're right in your initial assumption that there is nothing out there to model architecture easily. Visio is as good as we have right now.

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

#30

Post by richardw »

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…

Nice thing about e.g. EA is that your aren't just drawing pictures. You're able to collaborate on models that are surfaced on views, so a change is global and you can see where else e.g. a component is used.
Post reply on HN