README: Add instructions for creating each entry type (#323)

Co-authored-by: Kevin White <[email protected]>

Author: kfranqueiro

README.md

@@ -52,25 +52,25 @@ Additional directories with special meaning:
         - `{requirement-or-assertion-name}.md` - Defines content of an individual requirement or assertion
   - `terms/` - Contents of terms defined in the Glossary
 
-### Notable subdirectories under `src`
+### Notable Subdirectories under `src`
 
 - `src/lib/` - contains files that contribute to Astro build or template logic
   - `markdown/` - contains files implementing remark and rehype plugins, to transform output of
     Markdown files
 
 ## Editing the Guidelines
 
-### Supported fields
+### Supported Fields
 
-This section explains the fields available to frontmatter defined at the top of markdown files
+This section explains the fields available to frontmatter defined at the top of Markdown files
 for guidelines, requirements/assertions, and terms, and within JSON files for groups.
 
 For those unfamiliar with the term, frontmatter refers to YAML written at the top of a file,
 surrounded on each side by a line consisting of 3 hyphens.
 
 See existing files under the `guidelines` folder for examples.
 
-#### Common fields
+#### Common Fields
 
 These are available to multiple data types, as specified in each respective section below.
 
@@ -92,7 +92,7 @@ Represents each third-level heading that multiple guidelines are grouped under.
 Each group is defined in a JSON file, with its child guidelines located in a
 subdirectory with the same name.
 
-- Supports common fields: `children`, `status`
+- Supports [common fields](#common-fields): `children`, `status`
 - No additional unique fields
 
 #### Guidelines
@@ -101,17 +101,19 @@ Represents each fourth-level heading that multiple requirements/assertions are
 listed under. Each guideline is defined in a Markdown file, with its child
 requirements/assertions located in a subdirectory with the same name.
 
-- Supports common fields: `children`, `howto`, `status`, `title`
+- Supports [common fields](#common-fields): `children`, `howto`, `status`, `title`
 - No additional unique fields
 
 #### Requirements and Assertions
 
 Represents each fifth-level heading specifying an individual requirement or assertion.
 
-- Supports common fields: `howto`, `status`, `title`
+- Supports [common fields](#common-fields): `howto`, `status`, `title`
 - `needsAdditionalResearch` - Optional boolean, indicating whether to
   display a "needs additional research" editor's note
 - `type` - Optional string: `foundational`, `supplemental`, or `assertion`
+  - If not specified, the entry will be rendered as "Requirement"
+    (with neither "Foundational" nor "Supplemental" qualification)
 
 #### Terms
 
@@ -126,7 +128,7 @@ Represents each `dt`/`dd` pair appearing in the Glossary section.
 
 ### Additional Markdown features
 
-#### Definition lists
+#### Definition Lists
 
 Definition lists can be specified directly in Markdown via the following format:
 
@@ -143,11 +145,11 @@ Another shared term
 :   Another shared definition
 ```
 
-### Custom directives for guidelines Markdown
+### Custom Directives for Guidelines Markdown
 
 For more concrete examples, search for these directives in the repository.
 
-#### Decision trees
+#### Decision Trees
 
 The following block will be transformed into a decision tree `details` element,
 with "Which foundational requirements apply" summary automatically included:
@@ -193,7 +195,7 @@ Your content here
 :::
 ```
 
-#### Glossary term references
+#### Glossary Term References
 
 The text inside `:term[...]` will be transformed into a link referencing a term in the glossary,
 and can be used inline within blocks of text:
@@ -202,6 +204,106 @@ and can be used inline within blocks of text:
 ... is :term[programmatically determinable].
 ```
 
+## Creating New Entries
+
+General notes:
+
+- All instructions/examples in this section operate within the `guidelines` folder
+- File and folder names should be in [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case) (all lowercase, hyphen-delimited)
+- [See `title` under Common Fields](#common-fields) above regarding how
+  entry names map to titles by default, and how to override with a custom title
+- Remember to add appropriate frontmatter; see the subsection under
+  [Supported Fields](#supported-fields) for the relevant entry type
+- Other existing entries may be helpful to look at as examples, especially with
+  regard to JSON or frontmatter syntax
+
+### New Group
+
+For illustrative purposes, this refers to the new group as `group-name`.
+
+To create a new top-level group:
+
+1. Under the `groups` folder, create a subfolder for the new group
+   (e.g. `groups/group-name`)
+1. Also under the `groups` folder (not the new subfolder),
+   create a JSON file with the same basename as the new subfolder
+   (e.g. `groups/group-name.json`), with the following content:
+   ```json
+   {
+     "children": [
+     ]
+   }
+   ```
+1. Edit `index.json` (directory under the top-level `guidelines` folder)
+   to add an entry in its `children` array for the new group
+   (again using the same basename, e.g. `group-name`)
+   - This is what makes the group appear in the document structure,
+     and determines its order among the other top-level groups
+1. Follow the instructions below to create at least one guideline
+   within the group, and at least one requirement or assertion within
+   each guideline
+
+### New Guideline
+
+For illustrative purposes, this refers to the existing parent group as `group-name`
+and the new child guideline as `guideline-name`.
+
+To create a new guideline:
+
+1. Under the desired group's folder, create a subfolder for the guideline
+   (e.g. `groups/group-name/guideline-name`)
+1. Edit the JSON file for the group (e.g. `groups/group-name.json`)
+   to add an entry in its `children` array for the new guideline
+   (again using the same basename, e.g. `guideline-name`)
+   - This is what makes the guideline appear in the document structure,
+     and determines its order among the other guidelines under the same group
+1. Also under the group's folder (not the new subfolder),
+   create a Markdown file with the same basename as the new subfolder
+   (e.g. `groups/group-name/guideline-name.md`)
+   - To prevent the build from failing before any requirements or assertions are added,
+     include the following initial content:
+     ```
+     ---
+     children: []
+     ---
+
+     @@ add guideline text here
+
+     ```
+     We will expand `children` to a multi-line list when adding requirements/assertions.
+     Note that including some content after the frontmatter is also necessary for the build to function.
+1. Follow the instructions below to create at least one requirement
+   or assertion within the guideline
+
+### New Requirement or Assertion
+
+For illustrative purposes, this refers to the existing parent guideline as `guideline-name`,
+its parent group as `group-name`, and the new child requirement as `requirement-name`.
+
+Note that the process is the same for requirements or assertions; the only difference is
+the value of `type` in the entry's frontmatter
+(see [Fields for Requirements and Assertions](#requirements-and-assertions)).
+
+1. Under the desired guideline's folder, create a Markdown file
+   (e.g. `groups/group-name/guideline-name/requirement-name.md`)
+1. Edit the Markdown file for the guideline (e.g. `groups/group-name/guideline-name.md`)
+   to add an entry in its `children` array for the new guideline
+   - This is what makes the requirement/assertion appear in the document structure,
+     and determines its order among the other entries under the same guideline
+   - Arrays in frontmatter can be expressed similarly to Markdown lists, e.g.:
+   ```
+   ---
+   children:
+     - requirement-name
+   ---
+   ```
+
+### New Term
+
+Creating a glossary term is more straightforward, since there is no hierarchy:
+create a Markdown file under `terms`, then populate its content and any applicable
+[frontmatter](#terms).
+
 ## Environment Variables
 
 ### `WCAG_DIFFABLE`