DefangLabs / DefangLabs/defang-docs

Reorganize by diataxis

Open
#245 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.