hackforla / hackforla/peopledepot

Structure docs directory according to diataxis framework

Open
#184 2 comments 0 reactions 0 assignees View on GitHub
complexity: medium feature: docs: PD team documentation PII: FALSE role: dev lead s: PD team size: 2pt
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.