HackerTrans
TopNewTrendsCommentsPastAskShowJobs

zorg42

no profile record

Submissions

Making (sw-architecture) documentation fun again

innoq.com
2 points·by zorg42·3 वर्ष पहले·1 comments

[untitled]

1 points·by zorg42·4 वर्ष पहले·0 comments

[untitled]

1 points·by zorg42·4 वर्ष पहले·0 comments

[untitled]

1 points·by zorg42·4 वर्ष पहले·0 comments

[untitled]

1 points·by zorg42·4 वर्ष पहले·0 comments

[untitled]

1 points·by zorg42·4 वर्ष पहले·0 comments

Documenting software architecture with arc42

innoq.com
146 points·by zorg42·4 वर्ष पहले·32 comments

comments

zorg42
·3 वर्ष पहले·discuss
apply the established idea of "one-page documentation" to software architecture.
zorg42
·3 वर्ष पहले·discuss
All of the arc42 documentation is written in English, and the template itself is available in seven different languages.

See, e.g., https://docs.arc42.org

Apart from one of the founders (me) being German, it's no "German thing", but hopefully helpful to all kinds of systems.
zorg42
·4 वर्ष पहले·discuss
a small gallery of (ai-generated) images showing different art styles.
zorg42
·4 वर्ष पहले·discuss
A collection of Yoda portraits, purely generated by various AI systems.
zorg42
·4 वर्ष पहले·discuss
I would have liked a few diagrams describing some of your ideas, structures or internal processes, instead of using only text.
zorg42
·4 वर्ष पहले·discuss
QuickTime can record a window... low computational overhead, and built-in.
zorg42
·4 वर्ष पहले·discuss
alternatively, head over to the extensive documentation site(s):

https://docs.arc42.org and https://faq.arc42.org

both are free to use and hosted on public repos on Github.
zorg42
·4 वर्ष पहले·discuss
Right you are, it's definitely not new.

arc42 has been used in practice since 2004. The newest version 8.0 has been released Febr. 2022.

We incorporated user feedback (plus our own experience in real-time, embedded, data warehouse and e-commerce systems)..

(I'm one of the authors of arc42)
zorg42
·4 वर्ष पहले·discuss
arc42 is NOT part of the iSAQB Foundation curriculum. Depending on trainers, it might be covered within iSAQB trainings. If you are interested, you should check with your preferred training organisation in advance.

(I'm the author of arc42, so I'm biased).
zorg42
·4 वर्ष पहले·discuss
SysML (like UML) is a diagramming/modeling notation. Neither of them proposes any high-level structure for documentation.

arc42 proposes ONLY a high-level documentation/communicatin structure, and is notation agnostic: I've often used it with UML, and with informal box-and-lines diagrams.
zorg42
·4 वर्ष पहले·discuss
(I'm the author of the article)

I've written about requirements for docu-tools https://www.innoq.com/en/articles/2022/01/principles-of-tech...

In short: You need text + diagramming tools. Go as light as possible, start small (draw.io and Markdown/AsciiDoc). Use high-end modeling tools (like Enterprise Architect or ArchiMate only in larger teams and/or with formal documentation requirements (20+ devs). Have a look at docToolchain.
zorg42
·4 वर्ष पहले·discuss
Peter Hruschka, one of the authors of arc42, is a colleague of the Robertson family, who authored Volere. All are members of the AtlanticSystemsGuild
zorg42
·4 वर्ष पहले·discuss
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
zorg42
·4 वर्ष पहले·discuss
thanx, I fixed that.
zorg42
·4 वर्ष पहले·discuss
https://www.handelsblatt.com/
zorg42
·4 वर्ष पहले·discuss
arc42 is a practical, pragmatic way to communicate and document software architectures. Here's a brief introduction.
zorg42
·4 वर्ष पहले·discuss
It's always the same: you get what you pay for. No company offers something for free: If it doesn't cost anything, you're the product:

They will use usage-data to optimize their commercial offerings, they will try out features in non-critical (aka: free) accounts first - so not to offend the paying customers.

In some cases (e.g. free web-mailers like gmx, Instagram, FB etc) the free versions are mainly vehicles for advertising.

Why should Oracle be any different? I cannot see their motivation to offer anything for free... they are *only* money-driven.
zorg42
·4 वर्ष पहले·discuss
thanx - pragmatic collection of suggestions