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

121–130 of 239 posts

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

#121

Post by platz »

quickthrower2 wrote: post #116
platz wrote: post #99

Earlier quoted context omitted.

But my domain model is Store ===== Id int Col1 varchar Col2 varchar Col3 varchar ... Col134 varchar foreignKey1 varchar foreignKey1Type varchar foreignKey2 varchar foreignKey2Type varchar ... foreignKey10 varchar foreignKey10Type varchar validFrom varchar validTo varchar isActive boolean deleted boolean

Looks like a schema to allow the code to decide the real schema at runtime. A poor mans mongodb.

This is only a slight exaggeration of real things that exist in products like SharePoint or Visual Studio Team Services

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

#122

Post by basdp »

jimjimjim wrote: post #103
basdp wrote: post #71

Earlier quoted context omitted.

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.

So you're calling (f.e.) Amazon a shack?

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

#123

Post by basdp »

bdittmer wrote: post #81
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…

“Try moving towards architectures like micro services. KISS.” I don’t think you have worked with micro services, or more importantly have had to manage them.

All the time.

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

#124

Post by mikevin »

cubano wrote: 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…

This is why I dislike it when technical documentation itself becomes a goal. Detailed documentation never seems to be up to date in the real world. I've had far better experience with concise documention about high level concepts and structures and diving into the actual implementation for any details.

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

#125

Post by musha68k »

I used to “draw” ER/Flow/Activity/Sequence diagrams through various DSLs that would output PNG files with Graphviz but for quite a while now I like to marry “hand-drawn” ASCII diagrams with a README-driven-design-and-development process.

Embracing the constraints of a simple README for particular sub-systems lets me also put together general systems overview documents very easily after.

That said pencil & paper / whiteboard almost always comes first of course.

http://tom.preston-werner.com/2010/08/23/readme-driven-devel...

https://monodraw.helftone.com

http://asciiflow.com

Good non-ASCII alternative (for hyperlinked sharing in wikis etc):

https://www.lucidchart.com

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

#126

Post by TravelAndFood »

slx26 wrote: post #40
segmondy wrote: post #8

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

This is why I agree with other commenters who say that there's no good way to do this: with pencil and paper, you can't make changes / expand / remove parts so easily, it's harder to make big documents, it doesn't look that good, and yet... it still is one of the best ways to do it. P.S. I don't have anything against paper, and in fact I think it should be used more frequently while designing / prototyping / trying t…

Is there any software that translates a picture or scanned doc into a powerpoint? Seems like that could be useful: quickly churn out lots of boxes/arrows/text by hand, scan them, modify as necessary when translated.

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

#127

Post by jimjimjim »

basdp wrote: post #122
jimjimjim wrote: post #103

Earlier quoted context omitted.

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.

So you're calling (f.e.) Amazon a shack?

And the Burj Khalifa doesn't need an architect?

Sometimes the system doesn't need it sometimes it does. Not all software systems are the same.

I personally think the architect role is to look at the big picture first rather than trying to dictate the minutiae.

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

#129

Post by user5994461 »

pritambaral wrote: post #102
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/…

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

I use Outlook all the time. Format the text with Courier New to have fixed width.

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

#130

Post by myrloc »

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.

I use Cloudcraft to express the architecture of a number of my smaller projects. It's very easy to throw a few key parts together and get a basic idea out there. Exports in lots of resolutions, to SVG, and has shareable links.
Post reply on HN