DefangLabs / DefangLabs/defang-docs
Reorganize by diataxis
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 6
- Forks
- 7
- Avg merge
- 1d 6h
- Merged PRs (30d)
- 16
Description
Diataxis lays out four quadrants of documentation:
- Tutorials (learning oriented)
- How-to Guides (goal oriented)
- Explanation (understanding oriented)
- Reference (information oriented)
We have two primary sections:
- "Tutorials"
- "Concepts"
- Let's rename "Tutorials" as "Guides"
- Let's create a new "Tutorials" section with the "Getting started" article
- Let's also create a "Tutorial" for all of the youtube videos that Raph has been doing
- Let's break up "Concepts" into "Reference" and "Explanation". Most of these articles are probably "Reference", but some of them could probably be moved into "Explanation"
Here's an article on the difference between Tutorial and Guide: https://diataxis.fr/tutorials-how-to/
And another on the difference between Explanation and Reference: https://diataxis.fr/reference-explanation/
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by inspecting the current documentation structure, especially the Tutorials, Concepts, and Getting started sections, then compare the articles with the linked Diataxis guidance. Done means the sections are reorganized into Guides, Tutorials, Reference, and Explanation, with Getting started and the listed YouTube videos placed appropriately and the existing Concepts articles classified.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100