c4-notation VS diataxis-documentation-framework

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...

Second this.

Reference for anyone looking I to it: https://c4model.com/

There is also quite a lot of options for helping create these diagrams. I've found https://structurizr.com/ to be the best of what I've tried so far.

What you are describing sounds a lot like C4: https://c4model.com/

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've found https://diataxis.fr/ to be an excellent framework on which to hang documentation efforts. It helps you to understand what kinds of documentation resources help users most.

Tailscale is building a remarkable moat at extraordinary pace: capabilities real commercial use needs, on pricing that doesn't penalize the security-minded startup.

One key difference with their platform is the recognition so often missed inside the HN bubble that most B2B are on M365 and Entra, not Google like 3 devs in a cafe.

Another key difference is emphasis on "everything as code" from config to policy, enabling gitops of course, but also easier integration and automation.

But the biggest differentiation seems to be solving corner cases that come up in real world use and rolling those out faster than firms can come up the curve in their own Zero Trust implementation. Tailscale must have an excellent forward-deployed product sensing practice, to either discover or listen to these problems from commercial users then tackle them and get it rolled out for all customers. Their docs are also use-case focused and self-service empowering: https://tailscale.com/kb/1300/production-best-practices with a clear understanding of how devs spend their time https://tailscale.com/kb/1360/developer-tools and generally organized by the "Diataxis" systematic approach to technical documentation authoring: https://diataxis.fr/

Finally, contrary to popular practice here, Tailscale don't have predatory pricing for SSO, no “SSO tax”.

The $0 plan includes SSO. Even if you're a one person shop, there's no reason not to get SSO going for yourself, every future SaaS you integrate with, and every future onboarding/offboarding will thank you. Switching to this later is far more costly than adopting it early, and we should all be supporting one another to make SSO (or Oauth2+OIDC) the norm instead of an "Enterprise Call Us" pricing discriminator.