Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Guide to Software Architecture Documentation

workingsoftware.dev

Post reply on HN
Print view View original

11–20 of 60 posts

Re: Guide to Software Architecture Documentation

#11

Post by Aeolun »

29athrowaway wrote: post #10
rickette wrote: post #7

Big fan of C4. It's so simple most devs can contribute once some groundwork (initial diagrams) are done. Benefit is that software architecture is owned by the team, not just the architect. Haven't used arc42. Seems mostly a German thing. Has anyone outside German speaking countries experience with it?

> "It's so simple most devs can contribute" Oof... a lot to unpack in this phrase. You would be surprised to learn how much "devs" actually know. They may even recalibrate your ego a little bit if you were open to receive feedback. Those "devs" are the people that have to turn architectural documentation into reality, sometimes ignoring it completely.

I think they’re talking about the difference between senior and junior devs here.

Re: Guide to Software Architecture Documentation

#12

Post by blowski »

rickette wrote: post #7

Big fan of C4. It's so simple most devs can contribute once some groundwork (initial diagrams) are done. Benefit is that software architecture is owned by the team, not just the architect. Haven't used arc42. Seems mostly a German thing. Has anyone outside German speaking countries experience with it?

I base my architecture docs off the arc42 document. It’s useful as a base but always needs adapting to the specific system being documented.

Re: Guide to Software Architecture Documentation

#13

Post by sbarre »

Aeolun wrote: post #11
29athrowaway wrote: post #10

Earlier quoted context omitted.

> "It's so simple most devs can contribute" Oof... a lot to unpack in this phrase. You would be surprised to learn how much "devs" actually know. They may even recalibrate your ego a little bit if you were open to receive feedback. Those "devs" are the people that have to turn architectural documentation into reality, sometimes ignoring it completely.

I think they’re talking about the difference between senior and junior devs here.

Or just about the fact that in large enterprises a lot of the diagrams are owned by architects, and they're done in some esoteric inscrutable format where only the architect can make changes and updates to it _after_ talking to the developers.

I don't think this was a knock against developers.

Re: Guide to Software Architecture Documentation

#14

Post by [deleted] »

sbarre wrote: post #13
Aeolun wrote: post #11

Earlier quoted context omitted.

I think they’re talking about the difference between senior and junior devs here.

Or just about the fact that in large enterprises a lot of the diagrams are owned by architects, and they're done in some esoteric inscrutable format where only the architect can make changes and updates to it _after_ talking to the developers. I don't think this was a knock against developers.

[deleted]

Re: Guide to Software Architecture Documentation

#16

Post by ChrisMarshallNY »

Scubabear68 wrote: post #6

Over the decades I have come to dislike templates and various architecture formats, I seem to always waste time catering to the tool and format and not enough time communicating what’s important. I mostly do free-form diagramming, mostly of process level architecture and integrations. I haven’t looked at class level diagrams in years, which maybe says something about the limits of OOP and composition over inheritance…

I have used a sort of "UML Lite,"[0] from time to time, but that's about as formal as I get.

Normally, I have some kind of "block diagram," on what I call a "napkin sketch."[1]

A lot of documentation is in my head.

But I also tend to work on my own, or on standalone modules.

When we have a team (and I used to work for a Japanese engineering company, so this goes double), the standardized methodology becomes quite important.

[0] https://littlegreenviper.com/miscellany/swiftwater/the-curio...

[1] https://littlegreenviper.com/miscellany/forensic-design-docu...

Re: Guide to Software Architecture Documentation

#18

Post by AndrewKemendo »

This is all I'm typically looking for to fully grok a system:

-Working (or whatever is close) application I can play with (sandbox ideally)

-Readme with where all the docs are

-State Diagram, Flowchart, UML, (show me how & where data flows)

-Repo links (Maybe a cloned VM of a dev environment)

Re: Guide to Software Architecture Documentation

#19

Post by cortesoft »

Scubabear68 wrote: post #6

Over the decades I have come to dislike templates and various architecture formats, I seem to always waste time catering to the tool and format and not enough time communicating what’s important. I mostly do free-form diagramming, mostly of process level architecture and integrations. I haven’t looked at class level diagrams in years, which maybe says something about the limits of OOP and composition over inheritance…

> Over the decades I have come to dislike templates and various architecture formats, I seem to always waste time catering to the tool and format and not enough time communicating what’s important.

This is interesting, because I often find the opposite; that without a template or format, I spend too much time worrying about how to structure what I am creating instead of getting out the content.

Post reply on HN