diataxis-documentation-framework VS c4-notation

ways to write documentation, see e.g. )

To focus your content, leverage the Diátaxis framework.

Cover Image Credit: Diátaxis’ official documentation

For that topic some nice additional stuff: https://diataxis.fr/

I'm a little less than impressed by the presentation here. The idea that Divio is describing here is the Diataxis framework (https://diataxis.fr/), which "is the work of" (https://diataxis.fr/colophon/) Daniele Procida (https://vurt.eu/). Who, incidentally, is also giving the PyCon talk in the video on the page you linked (https://www.youtube.com/watch?v=t4vKPhjcMZg). But I don't see anything resembling attribution for the ideas. They aren't just common industry knowledge or "received wisdom". (And the "quote" from David Laing at the top isn't really accomplishing anything, either.)

Both is important. And related. Documentation needs to be discoverable. I was amazed when I tried jj (jujutsu, the "new git") and it popped me into some kind of weird textual user interface after executing `jj split` and I felt lost. I guessed, pressing `?` won't hurt and it told me just to use the mouse. The menues showed the related hot keys.

But the actual documentation of the tool has room for improvement. I needed a YouTube video to get started and that's rare for me.

So what I want to say is, that you need an intuitive, discoverable UI, but also a documentation that has each case (and if it's just for linking in 1st level support cases) _and_ is discoverable. And by that I mean both easy to grasp (e.g. following https://diataxis.fr/) and also can actually be found. I've had cases where a tool had good documentation, but actually finding it was the hard part.

I’m surprised no one has mentioned the C4 approach to diagramming yet, which is a prescriptive approach that helps to avoid most of these mistakes: https://c4model.com/

Start by formalizing the architecture. You don’t need heavy enterprise methodologies like TOGAF; use formats that fit the team and product. Frameworks like arc42 are suitable for complex systems, while simpler projects may only need C4 diagrams supplemented with a few additional visualizations.

Software Architecture is all about developing systems that scale and are maintainable. Clear visualizations will help teams to communicate the design effectively. The C4 model comes in handy for this task! But what is C4, and why should you care?

https://c4model.com/ is very useful for this. :-)

I've told it before, but when we were doing some clean sheet work a while ago I decided to use the C4 model and drew out the obligatory "Context" diagram with "user" "phone" "laptop" "app" sort of stuff... and then two hours later realized that because we had both an online and a semi-disconnected mobile app that could be offline, certain things -had- to use a queue and expect an arbitrary amount of time for a task to run, and it completely changed how we thought about the core of how we implemented something pretty important.

Sold. :-)

What sort of maps are you wanting to build? https://c4model.com/ seems to be the more popular standard for this style at the moment. https://github.com/plantuml-stdlib/C4-PlantUML makes this somewhat easy to code out. (And I think most cloud providers have addons for it.)

It sounded like it was working up to a C4 pitch but never got there. It bears a look exactly for this post's title.

https://c4model.com

Simon Brown is another person who has done a far better job than me of "democratizing" software architecture for developers. His talks [1] and workshops on architecture are exceptionally effective and his C4 architecture modeling language [2] is getting real traction.

I have youtube videos too [3] but they aren't as effective.

[1] https://www.youtube.com/results?search_query=simon+brown+arc...

[2] https://c4model.com/

[3] https://www.youtube.com/playlist?list=PLRqKmfi2Jh3uoMnZdaWmC...