Live data from Hacker News

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

news.ycombinator.com

101–110 of 239 posts

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

#101
post #19
post #16

I never knew architect was a thing in software.

The title is commonly found in heterogeneous projects where software isn't the solo driver. Ex: embedded systems Pretty much the title just describes a senior dev., who owns the software aspect of the project.

I'm working in automotive. The usual chain seems to be requirements engineer, system architect, software architect, software developer, integration engineer, tester.

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

#102

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

> The ASCII art diagram is the only format that can be integrated flawlessly into any email or documentation.

Certain email viewers like to ... "re-format" even fixed-width plain text and thus mis-render even ASCII art (looking at you, Outlook). Of course, every time I've received such reports, I've been able to brush the problem aside by simply asking people to use a different email viewer, or view the docs in a browser proper.

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

#103
post #71
post #46

Earlier quoted context omitted.

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

Shack - doesn't need an architect.

House - some do, some don't.

Commercial Building - yep.

Factory, Bridge or Infrastructure - you're insane if you don't.

Just like in construction, it depends on what you are building/expanding. Not all software is the same.

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

#104
post #87

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…

They are useful in articulating high-level insight on how systems integrate together.

A well done diagram would have an as of date, and some commentary along side boxes.

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

#105
Piggy backing on your post, I have a very large and complex systems of architectures (both hardware and software). I'd love to take that documentation and run analyzation on the data/node and their relationships (maybe via a graph DB in the backend and some rich search capabilities). Anyone know of any tools that not only help you draw and document, but interface with the diagrams via API?

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

#106

If you need documentation for architecture, your architecture is complicated. Improve the architecture instead.

Sometimes the least complicated architecture is still complicated (by human standards).

What i mean is, the simplicity is in the: "If i cameback to my project after 1 or 2 years, i can easily work with it because it has no complexity to remember".

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

#107
post #10

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

Informative and insightful videos. Thanks for sharing.

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

#108
post #91
post #87

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…

It's pretty straightforward - if it's pdf it's not versioned. If it's not versioned it's a fossil. The only thing I've ever done to reason about a new system is read the tests.

I second that. Reading tests is often more efficient than trying to learn about a system through documentation.

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

#109

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…

re: full disclosure,

I appreciate your reply and that it didn't end with "So, you should use program X (the one you work on) because it's the best software". Your objective response is great.

Post reply on HN