Authoring new guidelines and requirements in the repository

This document complements the Project Structure and Editing sections of the readme, stepping through how to add new entries at each level of the structure.

Creating a new group

1. Under guidelines/groups, create a subdirectory for the new group using kebab case, e.g. image-and-media-alternatives
2. Also under guidelines/groups, create a JSON file with the same name as the directory created in the first step, e.g. image-and-media-alternatives.json
   • Initialize the file's contents to the following:

     {
       "children": [
       ]
     }

3. Open guidelines/groups/index.json and add your new group's name (e.g. image-and-media-alternatives) at the point where it should appear in the overall document structure
   • For help with editing JSON, see Appendix A

Continue to creating new guidelines and requirements/assertions, as documented below.

Creating a new guideline

1. Under guidelines/groups, identify the directory and corresponding JSON file for the group that the new guideline is to be created under
2. Under the directory identified in step 1, create a subdirectory for the new guideline using kebab case, e.g. media-alternatives
3. Also under the directory identified in step 1, create a Markdown file with the same name as the directory created in step 2, e.g. media-alternatives.md
4. Edit the JSON file under guidelines/groups identified in step 1; in its children array, add a reference to the new subdirectory created in step 2
   • For help with editing JSON, see Appendix A
5. Start with the following structure, which contains example content:

   ---
   children: []
   status: developing
   ---
   
   Write description here.
   
   :::decision-tree
   For each item:
   1. Question 1?
      - Yes, (explanation). Continue.
      - No, (explanation). Fail.
   2. Question 2?
      - Yes, (explanation). Pass.
      - No, (explanation). Continue.
   3. Question 3?
      - Yes, (explanation). pass.
      - No, (explanation). Fail.
   :::

6. Adjust metadata (frontmatter) accordingly:
   • status can be any status indicator listed in the Explainer (in lowercase), or omitted if none should be shown
   • Typically, the title of the guideline is inferred from its filename, by converting hyphens to spaces and capitalizing the first letter of the first word. If this is not correct, it can be overridden by adding title: ....
     • For example, non-text-alternatives would become Non text alternatives by default, but can be corrected with title: Non-text alternatives
   • children: [] is initially empty and will be adjusted later, when adding the first requirement/assertion; see below

Creating a new requirement or assertion

1. Under guidelines/groups, find the directory for the containing group, then the subdirectory and corresponding Markdown file for the guideline that the new requirement or assertion will be created under
2. Under the directory identified in step 1, create a Markdown file for the new guideline using kebab case, e.g. audio-descriptions.md
3. Edit the Markdown file identified in step 1, and add to its list of children
   • For help with editing frontmatter, see Appendix B
4. Start with the following structure, which contains example content:

   ---
   status: developing
   type: foundational
   ---
   
   Write description here.
   

5. Adjust metadata (frontmatter) accordingly:
   • status may be any status indicator listed in the Explainer (in lowercase), or omitted if none should be shown
   • type may be foundational, supplemental, or assertion
   • If a requirement needs additional research, add needsAdditionalResearch: true as another line in the frontmatter
   • Typically, the title of the requirement/assertion is inferred from its filename, by converting hyphens to spaces and capitalizing the first letter of the first word. If this is not correct, it can be overridden by adding title: ....
     • For example, non-verbal-cues would become Non verbal cues by default, but can be corrected with title: Non-verbal cues

Appendix A: Working with arrays and objects in JSON

Entries in JSON arrays and objects must be separated by commas; in other words, all entries except the last will be followed by a comma.

When an array has only one entry, there is no comma:

[
  "first-entry"
]

When appending an entry to an array, remember to add a comma after the last existing entry:

[
  "first-entry",
  "appended-entry"
]

When inserting anywhere else in the array, remember to include a comma after the new entry:

[
  "first-entry",
  "inserted-entry",
  "appended-entry"
]

Appendix B: Working with arrays in YAML frontmatter

Frontmatter is the content seen at the top of Markdown files, delimited by --- lines above and below.

Arrays can be expressed similarly to bulleted lists in markdown, with each line beginning with - .

To add an item to an array with existing items, add another "bullet":

children:
  - previous-child
  - new-child
  - next-child

Empty arrays are a special case, as they must be represented similarly to JavaScript, with the value [].

To add an item to an empty array, convert it to a bulleted list.

Before:

children: []

After:

children:
  - new-child

Note the indentation of array items is significant, to indicate it defines the value of the children key of the parent object.