diataxis-documentation-framework
mark

diataxis-documentation-framework | mark | |
---|---|---|
85 | 6 | |
936 | 1,065 | |
1.6% | 1.9% | |
6.0 | 8.9 | |
about 1 month ago | 3 days ago | |
HTML | Go | |
GNU General Public License v3.0 or later | Apache License 2.0 |
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.
mark
-
Make writing documentation part of your pull request
Most companies that I worked for use Confluence for their documentation. However, this does not have to stop you from using git! You can sync your Markdown-based documentation to Confluence using mark!
- Mark – Sync your Markdown files with Confluence pages
-
Documentation as a service
Readme.md should be the very first source of documentation. From there we may have a nested “docs” directory all written in markdown and then as part of CI we sync that all into confluence on merges to dev using https://github.com/kovetskiy/mark
-
The Perks of a High-Documentation, Low-Meeting Work Culture
We use Mark[1] to automatically create Confluence pages from Markdown documents in our git repos. So we can have a review process for documentation changes, the documentation of the code can be in the repo with the code, and yet it can still be accessed without having to give permissions to view the code repo! Helpful with a proprietary monorepo.
[1] https://github.com/kovetskiy/mark
-
Ask HN: Software you hate but can't replace?
I used https://github.com/kovetskiy/mark at my last job where I had to use Confluence. It wasn't perfect and some touchup was generally needed after a sync but it definitely helped me stay sane.
-
An App's Single Source of Truth: Making the case for all resources in one repo
At the UAT/Production stage, the documentation is pushed to the Wiki using the extension of choice (most documentation parsers support the major wiki providers, like for Confluence there's Mark for Markdown, Official AsciiDoctor Exporter, and RST Exporter), or parsed into a DocBook/eBook/PDF for publishing.
What are some alternatives?
awesome-writing - An awesome list of information to help developers write better, kinder, more helpful documentation and learning materials
go-atlassian - ✨ Golang Client Library for Atlassian Cloud.
arc42.org-site - (jekyll-based) website for arc42.org - the template for communicating software architectures.
asciidoctor-confluence - Push Asciidoctor file to Confluence
c4-notation - Technical resources for using the C4 model for visualizing software architecture.
lazygit - simple terminal UI for git commands
documentation-framework - "The Grand Unified Theory of Documentation" (David Laing) - a popular and transformative documentation authoring framework
Gitea - Git with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD
technical-writing - A collection of materials relating to technical writing
Aviator - Xcode plugin that brings ⇧⌘T from AppCode over to Xcode
pgf - A Portable Graphic Format for TeX
Gogs - Gogs is a painless self-hosted Git service
