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

51–60 of 60 posts

Re: Guide to Software Architecture Documentation

#51

Post by willtemperley »

robertlagrant wrote: post #43
willtemperley wrote: post #42

In day to day work, checklists and Standard Operating Procedures are much more useful than diagrams. If there's a yak-shaving exercise, write it down as an SOP. It'll become obvious if the process is flawed or a target for automation. If making schema changes, document exactly all the steps required to integrate, test and deploy the change. It's complicated and easy to screw up - but a checklist can prevent the silly…

These aren't the same type of thing. Diagrams are to communicate and discuss what could be/what is. Checklists are to remember to do things.

In a sense, true. Diagrams can be part of an operating procedure however - why not even write operating procedures for architects? Checklists to ensure they've consulted with developers, product owners and site reliability engineers. Checks to ensure the diagrams are up-to-date and actually useful.

Re: Guide to Software Architecture Documentation

#52

Post by pydry »

captaincaveman wrote: post #45
gardenhedge wrote: post #17

As with all documentation.. it will be out of date after a while.

So what? This argument gets thrown up by someone nearly every time documentation gets mentioned. 1. Does it matter if not entirely accurate with the as-is? It showed the previous state or intention, that is typically very useful and a lit better than nothing. 2. Your unit test are out of date when your change code yet that typically gets updated, or new tests added, and is typically more work than updating the docs.…

>Does it matter if not entirely accurate with the as-is?

Yes. I've lost more of my life to out of date misleading documentation than to documentation that didn't exist at all.

Re: Guide to Software Architecture Documentation

#53

Post by robertlagrant »

willtemperley wrote: post #51
robertlagrant wrote: post #43

Earlier quoted context omitted.

These aren't the same type of thing. Diagrams are to communicate and discuss what could be/what is. Checklists are to remember to do things.

In a sense, true. Diagrams can be part of an operating procedure however - why not even write operating procedures for architects? Checklists to ensure they've consulted with developers, product owners and site reliability engineers. Checks to ensure the diagrams are up-to-date and actually useful.

I don't see why you're talking about operating procedures. This is about good diagram / documentation formats. Nothing to do with checklists or SOPs.

Re: Guide to Software Architecture Documentation

#54

Post by specialist »

MrJohz wrote: post #39
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 like the concept of C4, but when I was using it, I struggled a lot with the feeling that we never really ended up creating diagrams that we'd later use. As in, we'd have a diagram in the documentation, and maybe I'd look at it occasionally if I wanted to remember the name of a particular component, but most of the time when we actually wanted to discuss architectural decisions or explain the system to a newcomer, w…

In my experience, our internal documentation had two tangible benefits.

The team explaining to itself what they were working on. That process was the value. Consensus and alignment. Akin to forging culture. The artifacts generated were ephemeral. Basically performance art.

Managing upwards. PHBs want to see pretty pictures.

Re: Guide to Software Architecture Documentation

#55

Post by victor96 »

rubicon33 wrote: post #29
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?

Do you have any tools or guides to recommend for devs wanting to learn how to create "C4" documentation?

We created an interactive Miro workshop for teaching the C4 model structure.

https://miro.com/miroverse/c4-model-getting-started-workshop...

Re: Guide to Software Architecture Documentation

#56

Post by gardenhedge »

jeffreygoesto wrote: post #41
gardenhedge wrote: post #17

As with all documentation.. it will be out of date after a while.

Don't tell me it's impossible, tell me "I can't do it"... We had architecture sketches (informal, but highly taylored to show the gist of a system) that stayed valid and were used from after the first prototype to well after release, over a course of more than five years. It was a system of six embedded processors, 2 FPGAs, 5 different bus technologies, (luckily only) two different endianesses and coding and debuggin…

"Don't tell me it's impossible, tell me "I can't do it"..."

That's just rude so I'm not going to bother replying

Re: Guide to Software Architecture Documentation

#57

Post by gardenhedge »

captaincaveman wrote: post #45
gardenhedge wrote: post #17

As with all documentation.. it will be out of date after a while.

So what? This argument gets thrown up by someone nearly every time documentation gets mentioned. 1. Does it matter if not entirely accurate with the as-is? It showed the previous state or intention, that is typically very useful and a lit better than nothing. 2. Your unit test are out of date when your change code yet that typically gets updated, or new tests added, and is typically more work than updating the docs.…

Unit tests are tied to the build process for exact reason that they need to be updated with the code.

Re: Guide to Software Architecture Documentation

#58

Post by andorov »

specialist wrote: post #54
MrJohz wrote: post #39

Earlier quoted context omitted.

I like the concept of C4, but when I was using it, I struggled a lot with the feeling that we never really ended up creating diagrams that we'd later use. As in, we'd have a diagram in the documentation, and maybe I'd look at it occasionally if I wanted to remember the name of a particular component, but most of the time when we actually wanted to discuss architectural decisions or explain the system to a newcomer, w…

In my experience, our internal documentation had two tangible benefits. The team explaining to itself what they were working on. That process was the value. Consensus and alignment. Akin to forging culture. The artifacts generated were ephemeral. Basically performance art. Managing upwards. PHBs want to see pretty pictures.

Also changes to the diagram (at a certain resolution) require looping in specific senior people for review.

Re: Guide to Software Architecture Documentation

#59

Post by rubicon33 »

victor96 wrote: post #55
rubicon33 wrote: post #29

Earlier quoted context omitted.

Do you have any tools or guides to recommend for devs wanting to learn how to create "C4" documentation?

We created an interactive Miro workshop for teaching the C4 model structure. https://miro.com/miroverse/c4-model-getting-started-workshop...

awesome, thank you!
Post reply on HN