Documentation structure/organization

[fyliu]

This discussion is about how to structure the documentation site.

The popular way is to keep each document focused on one type of user and use, and not try to do too many things at the same time with lengthy, difficult to maintain documents. Our current "How to create a table and API endpoints" is an example of trying to be everything. It can, instead, keep to a simpler tutorial function and link to the appropriate dedicated documentation in other areas.

The most popular way to define documentation types is the diataxis framework by Daniele Procida: https://diataxis.fr

• Explanation
• Tutorial
• How-to
• Reference
  

In another talk by Meredydd Luff, he talks separates Reference into 2 and adds Q&A

• Explanation
• Tutorial
• How-to
• API Doc
• Reference
• Q&A (FAQ)