Spec format & Usability for editors
jstriebel opened this issue · 1 comments
jstriebel commented
We might want to revisit the spec format once v3 finalized content-wise, this collects some thoughts from my work with the v3 spec and from different discussions in the ZEP meetings. IMO larger changes should be done strictly afterwards to avoid conflicts with ongoing work regarding the v3 core spec and to avoid withdrawing any focus from it.
- The current division how concepts are explained is confusing sometimes. Currently, there is the Concepts and terminology section, some parts have additional specific sections, and many of them are referenced in the Metadata section again.
E.g. for data types:Data typein Concepts and terminology- Specific Data type section
data_typein the Array metadata
The concepts and terminology section are sometimes slightly too detailed. All of those sections should have cross-links to ease navigation between them. A short index with links to definitions in the end would be great IMO
- cross-references etc are quite complicated atm
- Some parts use quoted blocks to separate sections, e.g. the different parts in Concepts and terminology. This prevents cross-links to such parts.
- It would be great to have better guidelines for edits in the README, e.g. mentioning the ZEP process, technical documentation (sphinx, rst, …), having templates for extensions/stores/dtypes/etc.
- OME uses bikeshed for the spec (via markdown-to-spec, but isn't super happy with it as well, see ome/ngff#147. Since there's quite an overlap between the contributers with this project, it might make sense to consider using the same tool.