When designing and creating the document for the specification, the following guidelines should be adhered to.
The specification:
- must not specify that a specific technology, software package/library, or cloud provider must be (or is recommended to be) used
- can use examples that show a specific technology, software package/library, or cloud provider to demonstrate a concept
- should use lots of figures and examples to help visualize the content of the specification
- must keep figures and examples close to the normative prose
- must not rely on figures to define the specification, normative prose is always required to make precise specifications
The specification content:
- must have a Table of Contents which makes sense and the ordering of content should be sensical, headings should help people identify the section they are looking for
- must be written with an overall model before digging into the details. Each section will start with an overview of the feature and description
- should be written in order, so when read top to bottom any referenced content has already been covered in a previous section
Some of these items have been formed based on this W3C video on Best Pracitices for Editing W3C Specifications