[HN Gopher] Documenting software architecture with arc42
___________________________________________________________________
Documenting software architecture with arc42
Author : zorg42
Score : 133 points
Date : 2022-08-05 09:01 UTC (13 hours ago)
(HTM) web link (www.innoq.com)
(TXT) w3m dump (www.innoq.com)
| dathanb82 wrote:
| I was prepared to be upset that this article is an almost word-
| for-word copy of the "overview" page on the arc42 website
| (https://arc42.org/overview). But then I saw that the author is
| one of the arc42 maintainers. Now I need to find another target
| for my righteous indignation.
| nrawe wrote:
| This isn't really new. Architecture Definition Documents like
| this have been around for a long time.
|
| All the same, it's great to see the approach being promoted
| because there's a very real need for ADD's to exist.
| stunpix wrote:
| I would say arc42 is quite recognized documentation framework
| among software architects in Germany. My team is working with one
| major German automotive group and we/they are using slightly
| modified arc42 to document architectural parts + requirements for
| one of their core sw platforms.
|
| Also as far as I'm aware arc42 is a part of training courses for
| iSAQ certification for sw architects.
| pwdisswordfish9 wrote:
| The footnotes in this are messed up. The first one, when clicked
| the first time, landed in the middle of the article text, instead
| of at the footnote anchor. It looks like there's some misguided
| JS value-add lib in use here, which is meant to produce some
| smooth scrolling effect, but ends up making it worse...
|
| The reference to the second is mangled and appears in the text as
| "[docs^]".
| zorg42 wrote:
| it's free and open-source.
|
| it has been translated to EN, ES, DE, NL, IT and UA
|
| it's available for AsciiDoc, Markdown, docx, textile, Confluence
| and numerous other technical formats.
|
| many examples, hints and tips on https://docs.arc42.org
| smartmic wrote:
| Reminds me very much of the Volere Requirements Spec template[1].
|
| There are many ways to Rome, but remember, Rome wasn't build in a
| day (or with a single architecture plan).
|
| [1]https://www.volere.org/templates/volere-requirements-
| specifi...
| wirrbel wrote:
| i remember listening to a German-language podcast with the
| arc42 authors and they did mention volere. I forgot about the
| mutual history, but I think there was some resonance.
| zorg42 wrote:
| Peter Hruschka, one of the authors of arc42, is a colleague
| of the Robertson family, who authored Volere. All are members
| of the AtlanticSystemsGuild
| hanszarkov wrote:
| Many of my documents do indeed have a similar layout for design
| and it is nice to see efforts like this to create more rigor in
| SW architecture. As a practitioner (and being opinionated), I
| have these observations:
|
| - The "Building block view" is really the high level Structural
| Design. I tend to use structural decomposition to relay this
| information, iteratively breaking down into subsystems,
| components, etc. For this reason I prefer the term Structural. -
| The "Runtime view" is really the Behavioral Design of the system,
| the sum of behaviors of a system is what you see at runtime.
|
| I wonder if the terminology chosen for arc42 comes from a more
| academic or earlier time in SW architecture and design.
|
| I'm also a fan of the C4 Model[1] for visualization. So I think
| I'm going to try to incorporate the two together, like, utilize
| arc42 for a formal and disciplined approach to architecture
| documentation coupled with the informative visual paradigm of C4
| Landscape, Context, Containers, and Components.
|
| [1] https://c4model.com
| yardshop wrote:
| As I was reading this I felt that it overlapped and
| complemented the C4 approach in a lot of places. There's even a
| superficial connection: C4 is contained in the title!
| hanszarkov wrote:
| Agreed, the one thing I really think Simon [1] got right
| about visuals is the information they relay. Seeing a box
| diagram is one thing, e.g. boxes, arrows, names of tech (omg,
| @see AWS diagrams - they're really unexpressive deployment
| diagrams).
|
| Compare that to a C4 Landscape or Context diagram - and its
| just night and day - so much more meaningful information and
| the ability to express not just structure, but to provide
| hints at data flows, actors, and externalities. In the end,
| I've found the most value for C4 in communicating
| architecture to upper management and new hires. These
| diagrams really make more sense than boxes and lines.
|
| For arc42 I find the document content really appealing - its
| like engineering thinking. There is no standard
| template/model for design docs, perhaps this could start a
| baseline or trend to do something similar. I do still prefer
| Structural and Behavioral classifications.
|
| [1] Simon Brown, creator of C4 https://simonbrown.je/
| VanTodi wrote:
| Can confirm that it's a great framework. We use it in all our
| Team and just having the same structure is a great start. It's a
| bit tedious the find the right place for the information in the
| beginning, but overall we are were happy with it
| vitiral wrote:
| I'm confused, how is this different than a markdown file or
| google doc? Is the advantage that it has pre-specified headings
| with suggestions for the content?
|
| I feel like I'm missing something.
| potamic wrote:
| Shouldn't the solution strategy come after architecture decisions
| and concepts? I would think these would influence the solution
| significantly.
| frederikb wrote:
| As the author of arc42 writes in the article, the order of the
| chapters does not imply the order in which they should be
| decided upon and written.
|
| In addition he writes that you might have already documented
| the most important decisions as part of the solution strategy
| chapter.
|
| Most importantly, pick and choose based on your own judgement
| and experience those parts that you need and make it your own -
| in my experience arc42 has always been a good starting point
| when starting fresh or as a reference when evaluating existing
| documentation.
| ijidak wrote:
| Question. What tools are people using for architecture
| documentation besides Visio?
|
| What's the most productive tool you've found?
|
| I keep going back to Visio, but I really want a tool purpose
| designed for quick architecture diagrams that's more opinionated.
|
| Visio is so open ended, to me, it feels only slightly more
| efficient than using Photoshop.
| thisOtterBeGood wrote:
| Im using draw.io Just because it integrates Well to jira and
| confluence, But there really isnt much difference apart from
| license costs.
| ulrikrasmussen wrote:
| I'm using yEd, but that likely has the same issues as you
| mention, being very open-ended and requiring lots of
| micromanagement of styles and layouts. Perhaps you are seeking
| a tool such as plantuml in which you specify your diagrams
| textually and have them rendered by a compiler. It only
| supports a specific set of diagram types, primarily from the
| UML family, but I think it's also possible to install a third
| party C4 style.
| joshka wrote:
| Damn, this is really excellent. Over the course of my career I've
| written many tech specs, plans, one pagers, six pagers,
| functional requirements docs, ... etc. Each has been missing
| something, been too verbose, had sections that really don't
| integrate well. It's nice to see something a little more cohesive
| and rationalized.
|
| Even if I don't ever use Arc42 explicitly in the future, this is
| a great reference of what things to remember and include in
| whatever other format of initial spec. Thanks for the overview.
| [deleted]
| bloopernova wrote:
| I'll show this to my teammates and see if they like it. I really
| appreciate having everything laid out like this!
| fallingmeat wrote:
| To anyone who has experience with Arc24; How does this compare to
| the MBSE/SysML framework from OMG? https://www.omgsysml.org/what-
| is-sysml.htm
| zorg42 wrote:
| arc42 is a practical, pragmatic way to communicate and document
| software architectures. Here's a brief introduction.
| elcapitan wrote:
| If you're reading German, there's also a book on arc42 by the
| same author (Gernot Starke), "arc42 in Aktion".
| 1983054104 wrote:
| They also mention ADR (architecture decision records). Even if
| it's yet another fad, most companies I've worked for really
| needed a framework like this.
|
| I have only skimmed it so far but I'll definitely talk to the
| managers and architects at my company about it. Any kind of
| formalization on this topic is greatly needed.
___________________________________________________________________
(page generated 2022-08-05 23:01 UTC)