fyliu
commented
21 hours ago So the author isn't recommending using diataxis as a site structure, but as a guide to keep in mind when writing documentation. However, since there aren't real documentarians here in the group, whose role is to work on documentation, having a more explicit structure based on the documentation types would help remind developers and managers what audience and purpose they are writing for.
I would recommend a folder structure like this:
└── docs
├── about
│ ├── overview.md
│ ├── project_structure.md
│ └── github_actions.md
├── topics (explanation)
│ ├── authentication.md
│ └── Notes.md
├── tutorial
├── howto
│ └── authenticate_cognito.md
├── ref
│ └── api_endpoints.md
├── contributing
│ ├── index.md
│ ├── team.md
│ ├── dev_environment.md
│ ├── documentation.md
│ ├── git.md
│ ├── tutorial
│ │ ├── index.md
│ │ ├── add-model-and-api-endpoints.md
│ │ └── create-initial-data-migrations.md
│ ├── howto
│ │ ├── index.md
│ │ └── run-local.md
│ └── tools
│ ├── docker.md
│ ├── index.md
│ ├── mkdocs.md
│ ├── pre-commit.md
│ ├── scripts.md
│ └── uv.md
└── index.md It would be best to be able to do something like this, where all the howtos and tutorials are in the same folder and hidden from navigation, and link to them from both the user and contributor docs. But it looks like mkdocs-awesome-pages-plugin may not support this.
└── docs
├── about
│ ├── overview.md
│ ├── project_structure.md
│ └── github_actions.md
├── topics (explanation)
│ ├── authentication.md
│ └── Notes.md
├── tutorial.md
├── howto.md
├── tutorial # hidden from nav
│ ├── add-model-and-api-endpoints.md
│ └── create-initial-data-migrations.md
├── howto # hidden from nav
│ ├── authenticate_cognito.md
│ └── run-local.md
├── ref
│ └── api_endpoints.md
├── contributing
│ ├── index.md
│ ├── team.md
│ ├── dev_environment.md
│ ├── documentation.md
│ ├── git.md
│ ├── tutorial.md
│ ├── howto.md
│ └── tools
│ ├── docker.md
│ ├── index.md
│ ├── mkdocs.md
│ ├── pre-commit.md
│ ├── scripts.md
│ └── uv.md
└── index.md
Dependency
166
167
Overview
We want to use the diataxis structure for documentation because it has widespread adoption in the python community and is an effective way to convey information to multiple audiences.
The idea is to separate technical documentation into 4 categories (tutorials, howtos, explanation, and reference), which are useful to different mindsets (study vs. work, practical vs. theoretical)
Action Items
After Merge
Resources/Instructions
What this means is to create folders to hold the different types of documentations:
And to keep the primary purpose in mind when writing documentation.