Are there any other resources in this space?
Guide to Software Architecture Documentation
21–30 of 60 posts
Re: Guide to Software Architecture Documentation
#22Are there any other resources in this space?
Re: Guide to Software Architecture Documentation
#23Earlier 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.
Exactly, I'm a dev myself.
Re: Guide to Software Architecture Documentation
#24Over 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…
[deleted]
Re: Guide to Software Architecture Documentation
#25You mean because of a svn:needs-lock? That was a useful feature for really unmergeable (binary) files which is not suppoted by Git because of its DVCS nature.
Re: Guide to Software Architecture Documentation
#26Big 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.
"most devs" was meant as "most fellow devs". My whole point is to make architecture documentation a team activity.
Re: Guide to Software Architecture Documentation
#27This feels like another scrum workshop or whatever they teach to non tech managers. Forcing a specific workflow without ever explaining why (context -> containers -> components -> code), not a single mention about the problem domain but just a generic framework you are expected to fit all problem domains into. You learn more about the framework before you learn about the problem. Example:
"Here's a container! It is either a Server-side web application, Client-side web application, Client-side desktop application, Mobile app, etc etc". Okay why? Why are you making this distinction? Why not just call it a web server, a web app, a mobile app? What could this concept of 'container' be so useful that you have to invent it and make everyone internalize it? Does it contribute to the discussion? Are you trying to arbitrarily force labels onto things so you can use the same lingo to talk about every problem?
Re: Guide to Software Architecture Documentation
#28As with all documentation.. it will be out of date after a while.
It's like code... code can be out of date after a while, too. The question is how easy it is to keep it updated and current. I think that's the biggest argument behind diagrams as code. Imagine you throw away your codebase each time you deploy your executable.
Re: Guide to Software Architecture Documentation
#29Big 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?
Re: Guide to Software Architecture Documentation
#30Diagrams are where architecture goes to die.
In my experience as a former head IT architect, the value of an architectural process is in management and communications. For example, finding out and documenting where your thought leaders are going (a technology acquisition plan) and how they plan to get there (a technology implementation plan). Those are from COBIT 4 BTW.