Create guidelines for describing an element in the specification document

This proposal is an outline for how to write about an element in the specification document. Some of the following section titles or their contents won't apply when writing about high-level topics such as blocks, spec-wide terminology, macros, etc. Creating guidelines for high-level topics may not be necessary, but if so, we'll do that in a separate issue.

Proposed structure of a specification section for an element

1. The document title is the name of the element
   • Generally, create one document per element, such as Paragraph, Sidebar, Strong Span
   • The filename should match the document title in most cases.
2. Description: A non-normative section describing the element and any applicable semantics and meanings.
   • Source examples: A subsection of Description showing source examples included from the TCK; this ensures they're accurate and valid
     • The source examples should be included from the tests in the TCK, not handwritten! A case would need to be made for any examples to be written in the document that aren't functionally sourced directly from a tested file.
3. Context: A section specifying the place, environment, or situation in which the element can be used. A context is a parent of the element; therefore, the element is a child of the parent in the ASG and DOM trees.
   • Q: Should this section be normative or non-normative?
4. Content model: A normative section. The content model of an element equates to the grammar rules for the contents of the element. The content model describes the children the element is capable of accepting. These children are represented as descendants of the element in the ASG and DOM trees.
   • The section should state the model, what the element accepts, whether it can be empty, whether it can be parsed to empty, and what it can be interrupted by
   • Attributes and metadata: A subsection of Content model that lists the attributes and metadata the element must accept
5. Possible section: Grammar (or) Grammar rules
   • Q: What differentiates the grammar/grammar rule section and the content model and metadata sections? That is, why is this section needed in the specification document?
6. ASG and DOM: A normative section containing the applicable snippets from the ASG schema and the DOM, potentially in a tabbed interface.
   • Should this section be a child of the content model section?
7. Q: Should we add a section or information in one of the sections that identifies whether the element is extensible?

As far as text usage and formatting, we need to decide if we want to:

• follow the formalized capitalization and usage of words such as MUST, SHOULD, etc. (there's an RFI for this sort of thing)
• try to consistently use those words in normative sections but don't capitalize them
• use some other terminology or styling to call out hard and soft rules

For this issue to be complete, I would like to be 75% confident we're using a communicative and usable structure, including clear section titles and sections in a logical order, and that the content in the sections clearly communicates to developers the information they must know while creating an implementation. However, we don't need to nail down every term or determine how we're going to functionally insert the ASG and DOM snippets into the specification from their tested single source.

When drafting up these guidelines, I created a few sample sections (Paragraph, Strong Span, etc.) and consulted the Unicode, HTML, JavaScript, and OpenAPI specs for structural information.