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:

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

Figure: New Rule button.

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.
- SEO Description A brief summary of rule's content. It appears below the title in search engine results and should be both concise and include relevant keywords.
- URI URI of the rule (the unique part of the URL)
  - Use dashes in your URLs
  - Make them short and readable (ditch the "do-you" and keep only the important keywords)
  - Make sure they are all lowercase
  - We avoid product names in URLs since they might change over the years (e.g. from Skype to Teams).
    That is why we have /video-background instead of /teams-background
    Note: It is fine to have product names in titles for SEO, since titles are easy to update
- Body The content of the rule. Consider using the SSW Rules Writer GPT for your 1st draft (if you have GPT Plus)
- 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
If you want to add images you first need to save your changes as a draft (see next step below). This will create a folder for your rule. Once saved, follow the instructions given on How to Add an Image.
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.

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'

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

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:

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
Go to the rules folder, and click Add file | Create new file
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 (including casing, so keep it all lowercase for consistency)
Edit the file by clicking the pencil symbol.
Consider using the SSW Rules Writer GPT for your 1st draft (if you have GPT Plus)
If you didn't use the GPT, copy the content of the rule template to this file
Tip: Read Do you use {{ }} for replaceable text?
Edit the frontmatter:
- type: Value must be set to 'rule'
- seoDescription: A brief summary of rule's content. It appears below the title in search engine results and should be both concise and include relevant keywords
- 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)
  - Make sure it is same as the folder name you created above
- 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
seoDescription: Discover insider tips for saving on hotel bookings! Compare prices on lastminute.com.au and stayz.com.au, but don't book yet. Learn how calling hotels directly can unlock exclusive deals and maximize your savings. Get the best accommodation deals for your trip. Start saving today!
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

Add the text of your rule in markdown. Use the tag  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.