Example projects as a 5th section?

[Apostolique]

How do you view example projects in this documentation system?

For example let's say I make a C# library. Then I make multiple complete projects that use that library. Those projects would be real world applications that people can look at to get inspired and learn. How does that mesh within the Diátaxis framework?

[macleod-ee]

This is the most important aspect of any documentation, if you had to choose one of them: Examples. They give a view into how the project operates, with real. World applications. Every project should have an /examples directory.

[evildmp]

@Apostolique The questions you need to ask about content:

Is this content describing

• practical steps, or
• theoretical knowledge?

Is this content what I need for my

• study (i.e. to gain knowledge and skills),
• work (i.e. to apply knowledge and skills)?

A list of example projects clearly represents theoretical knowledge, not actions (so it must be either Reference or Explanation).

And also clearly serves our study (acquisition of knowledge/skills), not our work (acquisition of knowledge/skills). So therefore it must be Explanation.

Tutorials/How-to guides/Reference/Explanation should not be thought of as a list of "sections". They are forms or modes of documentation. It's not possible to add new ones, it doesn't really make sense. There are four, because that's what emerges from the two-axis arrangement it identifies around the needs of a practitioner of a craft.