Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use the diataxis framework for the diataxis framework website? #107

Open
bew opened this issue Nov 22, 2023 · 0 comments
Open

Use the diataxis framework for the diataxis framework website? #107

bew opened this issue Nov 22, 2023 · 0 comments

Comments

@bew
Copy link
Contributor

bew commented Nov 22, 2023

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant