diataxis-documentation-framework
arc42.org-site


diataxis-documentation-framework | arc42.org-site | |
---|---|---|
85 | 16 | |
936 | 6 | |
1.6% | - | |
6.0 | 7.3 | |
about 1 month ago | 9 days ago | |
HTML | SCSS | |
GNU General Public License v3.0 or later | MIT License |
Stars - the number of stars that a project has on GitHub. Growth - month over month growth in stars.
Activity is a relative number indicating how actively a project is being developed. Recent commits have higher weight than older ones.
For example, an activity of 9.0 indicates that a project is amongst the top 10% of the most actively developed projects that we are tracking.
diataxis-documentation-framework
-
Breaking down common documentation mistakes
To focus your content, leverage the Diátaxis framework.
-
Understanding User Needs in Technical Writing: How Frameworks Like Diátaxis Help
Cover Image Credit: Diátaxis’ official documentation
-
Rules for Writing Software Tutorials
For that topic some nice additional stuff: https://diataxis.fr/
- Documentation chaotique ? Diataxis à la rescousse !
- Diátaxis – A systematic approach to technical documentation authoring
-
Every Board Game Rulebook Is Awful [pdf]
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.)
-
The Opposite of Documentation is Superstition (2020)
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.
- Diataxis pour organiser sa documentation
- Large language models reduce public knowledge sharing on online Q&A platforms
-
Ask HN: Technical Writing Resources
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.
arc42.org-site
-
A View on Functional Software Architecture
There a various standards for documenting software architecture, like arc42 or C4. While useful and somewhat well-known (there is certainly a correlation here), here architecture documentation can be further simplified, particularly due to the self-similarity of project and component. Following is a small template, that can also serve as a project's and component's README:
-
Architecture diagrams enable better conversations
I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/. It's very easy to embed a C4 diagram into a markdown document.
The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (for interactive diagrams and indexed search).
I also use https://d2lang.com/ for declarative diagrams in addition to C4, e.g., sequence diagrams and https://adr.github.io/ for architectural decision records. These are also well integrated into structurizr.
-
Documenting a software project
My general approach to documentation is a "software guidebook" (free e-book link) or arc42 ... complemented with diagrams and architecture decision records where necessary.
-
System Design How to?
In addition to a small number of diagrams, I'd recommend something like arc42 or my "software guidebook" (link for a free copy of my book describing this), plus some architecture decision records.
-
Solution Templates
Arc42 may give some inspiration https://arc42.org/
-
What's your process to create documentation for a new startup's application?
If you need more structure than ADRs then https://arc42.org is super useful.
-
Recommendations for an Online Introduction to Software Modeling
There are plenty of good resources out there for learning modeling languages and architectural documentation structures. For more lightweight methods, I'd recommend checking out resources like Simon Brown's C4 model for visualizing software architecture, Martin Fowler's UML Distilled: A Brief Guide to the Standard Object Modeling Language, Scott Ambler's Agile Modeling site, and the arc42 template for architectural documentation.
-
How to get good at writing design documents?
As you need to, you can get into topics like different modeling languages or documentation template libraries. These are going to be highly dependent on your organization, though, as different organizations have different standards for what and how to document design decisions. Personally, I've found that the arc42 documentation template plus the C4 modeling language plus the UML modeling language (see UML as sketch and UML as notes for more on lightweight UML) for the most detailed models (which are rarely needed outside of the most complex parts of a system) tends to be a good, agile, lightweight model for the kinds of things to think about when it comes to creating design documentation.
-
How to improve writing documentation?
We've started using Arc42 and C4 model & PlantUML for diagrams. Working out well so far.
-
About documentation
arc42 - arc42
What are some alternatives?
awesome-writing - An awesome list of information to help developers write better, kinder, more helpful documentation and learning materials
c4-notation - Technical resources for using the C4 model for visualizing software architecture.
architecture_decision_record - Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation
documentation-framework - "The Grand Unified Theory of Documentation" (David Laing) - a popular and transformative documentation authoring framework
exploring-the-testing-hyperpyramid - Code repo for the KotlinConf 2023 talk by @daviddenton and @s4nchez
technical-writing - A collection of materials relating to technical writing
structurizr-site-generatr - Static site generator for architecture models created with Structurizr DSL
mark - Sync your markdown files with Confluence pages.
java - Structurizr for Java
pgf - A Portable Graphic Format for TeX
jgmd - A directory of direct links to get your personal data from web services.

