evildmp/diataxis-documentation-framework

A systematic approach to creating better documentation.

The documentation system

A comprehensive and practical system that can help maintainers of product documentation.

Published at https://diataxis.fr

Author: Daniele Procida

License: CC-BY-SA 4.0

diataxis-documentation-framework's Issues

Use the diataxis framework for the diataxis framework website?

I was highly surprised when I realized that the website describing the framework does NOT follow what it describes.
When looking for tutorials or references it isn't always clear where to look without reading everything.

I saw a related post about this very subject but that didn't get any followup discussion/comments.
I believe it's an issue though, so I'm opening this instead.

The current side menu isn't clear what each section is, there is a mix of reference & explanation...

Copying what @wolftune said in that post, the website could/should be re-structured with something like:

• Tutorial: A guide through the experience of making all 4 types of documentation using some clear example case, even if silly
• How-to: Practical steps for separating things into the 4 types, for the step-by-step questions and answers to consider to flesh out each type, etc.
• Reference: There's some of this already, the summary tables and such, it's just mixed with explanation and incomplete
• Explanation: the whole Diataxis website seems primarily explanation right now

We may need another toplevel category for other pages.

---

Would you accept contributions to change the website structure?
Have you thought about this already?
Were there roadblocks that made you do the current structure instead?

In tutorial section know is written twice

broken link to Gitlab

At https://diataxis.fr/adoption/ there are two links to GitLab. The second one works. The one to https://docs.gitlab.com/ee/development/documentation/styleguide.html 404's

Use sphinx opengraph

This makes social previews for the site automatically really pretty:

https://github.com/wpilibsuite/sphinxext-opengraph

It should just be an "install and forgot" option, but it would make this tweet look nicer :)

https://twitter.com/readthedocs/status/1628814555420979200

What is the actual name?

Diataxis, I guess?

FWIW, I followed a link originally to the page at Divio which is titled "The Documentation System."

Then there is this quote (both here and there): "The Grand Unified Theory of Documentation" from David Laing. I did a little searching on the Internet, but could not suss out that reference.

Anyway, perhaps a little clarification might be in order?

These are great ideas that I would like to help spread, ideally with the correct name though. 😄

anti-pedagogical temptations invisible on dark mode

Maybe something to report to the theme rather than here...

open source license? is it thought as a collaborative project?

maybe I missed the info somewhere, where can I find the license file/note?
Was checking if it is possible to include the concept into Open Educational Resources.

Cheers

Humans should not be referred to as "it"

Tutorials > Food and cooking

The child is referred to as "it" several times.
I recommend the child be referred to with the gender neutral pronoun "they".

Example:
Old:
The child will learn, in its own time, at its own pace, through the activities you do together, and not from the things you say or show.

New:
The child will learn, in their own time, at their own pace, through the activities you do together, and not from the things you say or show.

INQUIRY : POSSIBLE LANGUAGE TRANSLATIONS

How many languages is diataxis documentation considering to be converted in?

Provide diataxis framework as an ebook

I'd love to read it on my kindle and share it as an ebook with my colleagues!

How-to guides "task-" vs "goal-oriented" inconsistency

https://github.com/evildmp/diataxis-documentation-framework/blob/main/how-to-guides.rst says How-to guides are "goal-oriented" while https://github.com/evildmp/diataxis-documentation-framework/blob/main/images/diataxis.png and https://github.com/evildmp/diataxis-documentation-framework/blob/main/images/overview-how-to.png say they are "task-oriented"

Duplicate words

Under 'Explanations', the subtopic "Talk about the subject" has a sentence with duplicate words.

"you should should be able to place an implicit (or even explicit) about in front of each title"

I wish to make an edit and send in a PR if it's ok?

Translation

Hi!
First of all, thanks for this brilliant work. 👏

It summarizes what I have been struggling for years to convince my fellow coworkers what a documentation should be.

It so valuable to me that I would like to translate it entirely to portuguese. What you think about that? And how we could accomplish it?

Update year in footer

Edit on GitHub links broken

Your "Edit on GitHub" links are broken, probably cause your string concatenation adds a redundant forward slash to the beginning of the second part.

Sources of the theme

I'd like to both use theme https://pypi.org/project/divio-docs-theme/ and to contribute some enhancements. However, it seems that https://github.com/divio/divio-docs-theme/ no longer exists. Are sources of the theme available in any other repo?

Add link to website in this repo?

In any case, thanks for the resource and its source!

Q: Why adoption page's removed?

I often reference the adoption page (which used to be at https://diataxis.fr/adoption) to get a general overview of how other peoples and teams approach to document their products, structure, etc.

But it looks like, via this commit, the adoption page was removed.

Any reasons why it was removed? And (of course) any chance to put it back? 🤔

Transifex status and join request approval

Hi there,

Opening this one to get a fresh update on translation and Transifex status:

• Is the project still interested in being translated?
• Are resources over at Transifex up to date?
• Is there anyone to accept my request to join French translation team over there?

Thanks in advance and have a nice week
TY

Opportunity to connect with the larger conversation

I appreciate the Diátaxis framework and the beautiful job your website does of laying out the four quadrants. As a long-time tech writer, naturally I kept thinking of related terms. For example, three of your quadrants directly map onto DITA information types. I see that you've thoughtfully compared Diátaxis with DITA in a Reddit conversation, where I found your replies insightful. Why leave this comparison out of your website, where knowledgeable people could most benefit from it?

Another term that came to mind is "modular writing," especially where you talk about organic growth taking place at the cellular level. Modular writing also applies when you talk about section headings that indicate the type of info within a module (such as "About ..." in an explanation heading). Much of what you say echoes Kurt Ament's seminal book "Single Sourcing: Building Modular Documentation" and other sources.

It would add depth to your website to acknowledge related terms and resources and share some perspective on them.

P.S. With 19 open PRs going back two years and 8 open issues going back to a year ago, it seems that you aren't into your website much any more. I hope that's not the case. It's a wonderful resource. Reading it has enriched my sense of the difference we tech writers can make for people.

Dark logo and dark-mode-ready content

Hey @evildmp, the current dark mode logo is white and has high contrast with the rest of the website and https://pradyunsg.me/furo/customisation/logo/#different-logos-for-light-and-dark-mode is a thing.
Also, it should ideally be SVG in which case, maybe, it won't be necessary to have two logo files and just make use of CSS media queries inside SVG.

Same goes for the rest of the imagery. While PNG supports transparent background, it'd be nice to have those images scalable too.

Note that if you ever decide to embed one of the images into the GitHub readme, you can also use SVG there as well as separate images with different URL fragments for the schemes.