Structuring the SHACL-UI specs

[tpluscode]

For a few months, I have been a mild advocate of Diátaxis. It is a set of guidelines which help write useful "documentation". TL;DR; it divided what constitutes documentation as a whole in 4 parts:

1. Tutorials
2. How-to guides
3. Conceptual guides
4. Reference guides

I find it quite useful and I may propose to aim for not just one ReSpec (side note, is bikeshed an option?) but up to four.

Specifically, a Reference guide would be more or less a vocabulary listing with ranges, domains, etc, and simple examples. Next, I would go for How-Tos to elaborate on using the spec to accomplish practical goals. Conceptual guides would also be useful, to discuss some design choices, etc. We may choose not to go for tutorials at all IMO...

[tfrancart]

IMH experience yes, I would decouple the reference documentation, hands-on how-tos tutorial, and an architecture documentation expliciting the design choices.