hackforla / hackforla/peopledepot
Structure docs directory according to diataxis framework
- Dominant language
- Python
- Stars
- 14
- Forks
- 37
- Avg merge
- 9d 15h
- Merged PRs (30d)
- 5
Description
### 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
- [ ] Create folders according to the diataxis structure
- [ ] Sort the documentation into the relevant folders
### After Merge
- [ ] Check #185 for completion
### Resources/Instructions
What this means is to create folders to hold the different types of documentations:
- [Tutorials](https://diataxis.fr/tutorials/): Learning-oriented
- How to do a complete thing with the system. Like implement a simple client.
- [How-To Guides](https://diataxis.fr/how-to-guides/): Problem-oriented
- How to solve specific problems. Like how to configure some component.
- [Reference](https://diataxis.fr/reference/): Information-oriented
- It'd be things like our API docs and generated code docs
- [Explanation](https://diataxis.fr/explanation/): Understanding-oriented
- called "topics" in some projects. It's a high level view of the concepts.
And to keep the primary purpose in mind when writing documentation.
---
- [Documentation with MkDocs
](https://realpython.com/python-project-documentation-with-mkdocs/)
- [diataxis.fr](https://diataxis.fr)
Contributor guide
Assessment
This issue has not been assessed yet.