How to Create Rules

Tip: use the Rules to Better Technical Documentation to help you create consistent and high quality rule content

Using Netlify CMS

Creating a new rule is easy with Netlify CMS. However, it is important to categorize the rule once this is completed, and this is done solely via GitHub editing. See How to Add and Edit Categories and Top Categories for more details.

Follow these steps to create a new rule:

1. Go to SSW Rules
2. Click on the 'New Rule' button.

Figure: New Rule button.

3. Fill in the fields in Netlify CMS.

   • Title The title of the rule as it will appear on the rule page. You should use a question here. E.g. "Do you know how to do this?"
     Note: Make your rule title generic enough. Keep in mind we don’t want to change the rule name if we change our mind about the content. For example, if we were to change the placeholder rule from using [ ] to {{ }}, then I would not want the rule name to change.
   • URI URI of the rule
     • Use dashes in your URLs
     • Make them short and readable (ditch the "do-you" and keep only the important keywords)
   • Body The content of the rule
   • Authors Used in the acknowledgment section
   • Related (Optional) List of related rules (note: individual rules only, not rule categories)
   • Redirects (Optional) You can add old URI's here so if someone navigates to the old URL, it will redirect them to the new one
   • Date Created Creation date of the rule
     • TODO: Add formatting for dates
   • Archived Reason (Optional) Used only for an archived rule

4. Click 'Save' to save your changes to the rule as a draft. Note: To delete these changes use the 'Delete unpublished changes' button next to 'Save'.

Figure: Changes saved as a draft.

5. When you are ready to publish your changes, setting the status to 'In review' submits your changes for approval before they are added to SSW Rules. Note: If you don't want to publish just yet, your changes will be waiting for you as a draft. Simply open the editor again when you're ready to continue editing.

Figure: Set the status to 'In review'

6. Check the status of your changes in the Workflow tab of Netlify CMS. You can see all changes that are drafted and in review.

Figure: See all your edited rules

7. Categorise your rule. See How to Add and Edit Categories and Top Categories

Manual creation in GitHub

Creating a new rule is a big change on multiple files, and so you need to make the changes on a forked repository, and merge them back into the base SSW.Rules.Content repository. Follow these steps:

1. Go to your forked repository: {{User}}/SSW.Rules.Content. If you don't have a fork of the SSW.Rules.Content repository, see the instructions in Editing with Forks
2. Go to the rules folder, and click Add file | Create new file
3. Name your file {{rule-uri}}/rule.md (e.g, 'do-you-encourage-experimentation/rule.md')
   Important: The folder name must be the exactly same as the uri
4. Edit the file by clicking the pencil symbol.
5. Copy the content of the rule template to this file
   Tip: Read Do you use {{ }} for replaceable text?
6. Edit the frontmatter:
   • type: Value must be set to 'rule'
   • archivedreason: Must be deleted or be left empty, used only for an archived rule
   • title: The title of the rule as it will appear on the rule page. You should use a question here. E.g. "Do you know how to do this?"
   • guid: Unique identifier of the rule in CosmosDb
     • You can use guidgen.com/ to get a guid
   • uri: URI of the rule
     • Use dashes in your URLs
     • Make them short and readable (ditch the "do-you" and keep only the important keywords)
   • created: Creation date of the rule
     • TODO: Add formatting for dates
   • authors: Used in the acknowledgment section
     • See How to Add an Acknowledgment
   • related: List of related rules (note: individual rules only, not rule categories)
   • redirects: You can add old URI's here so if someone navigates to the old URL, it will redirect them to the new one

See this frontmatter example:

---
type: rule
archivedreason: 
title: Accommodation - Do you know the best online accommodation websites?
guid: 8d59feea-03b4-4cfc-b26e-77b2655293d9
uri: the-best-online-accommodation-websites
created: 2015-04-28T05:06:33.0000000Z
authors: []
related:
- do-you-create-an-online-itinerary
- do-you-check-if-your-qantas-flight-is-eligible-for-a-"bid-now"-upgrade
- do-you-know-how-to-get-the-most-out-of-your-credit-card
- do-you-check-your-boarding-pass
- do-you-take-advantage-of-business-rewards-programs
redirects:
- accommodation-do-you-know-the-best-accommodation-websites

---

Figure: Example or Rule frontmatter

7. Add the text of your rule in markdown. Use the tag <!--endintro--> to mark where the short blurb (displayed on the category page when 'Show Blurb' is selected) ends and the body begins. The blurb should summarize the problem that the rule is solving and entice the reader to read more.

For example:

Markdown for the blurb. Outline the problem that the rule is solving.

<!--endintro-->

Markdown with the rest of the content (not shown in the blurb).

Figure: The use of endintro

Note: We usually have text only in these summaries, so avoid including videos and images within the intro.

8. Merge your changes, see Merging Your Fork

Automated creation

TODO: Describe the process

Next Step

See How to Add and Edit Categories and Top Categories