How to Create Rules

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

Using TinaCMS

Creating a new rule is easy with TinaCMS. Everything can be done using the Tina admin panel (see instruction bellow). We strongly recommand to NOT update rules directly via GitHub repository, or only for debugging.

Follow these steps to create a new rule:

1. Go to SSW Rules
2. And click on the button "Create a new Rule" on the top right corner

Figure: New Rule button.

3. Enter your TinaCMS credential if your are not connected.
4. You arrive in the Tina Admin panel where all the rules are listed. Click on the "Add file" button on the top right corner.

Figure: Add file button.

5. Fill the required fields

   • 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 (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
   • The filename will be automatically generated.

6. Click Save. You will then be guided to create a new branch for your changes

7. Once the process is finished, edit the rest of your rule. Go to the Rules collection and find your new rule at the top of the list. Open it to edit, and make sure to link it to at least one category.

Note: In the body’s rich-text editor, you can click Embed to add specific items (Introduction, Email, Image, YouTube, etc.)

8. Click "Save" again. Your changes will be committed automatically to your branch and your pull request

9. Navigate to SSW.Rules.Content | Pull Requests and open your pull request. Add a title and fill out the description fields (As per Do you know how to write a good pull request?)

10. Once everything looks good, scroll down and click "Ready for review" 😉

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 public/rules folder, and click Add file | Create new file
3. Name your file {{rule-uri}}/rule.mdx (e.g, 'do-you-encourage-experimentation/rule.mdx')
   Important: The folder name must be the exactly same as the URI (including casing, so keep it all lowercase for consistency)
4. Edit the file by clicking the pencil symbol.
5. Consider using the SSW Rules Writer GPT for your 1st draft (if you have GPT Plus)
6. 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?
7. 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
   • categories: List of categories for this rule (full path required)
   • sidebarVideo: Promoting Shorts

See this frontmatter example:

---
archivedreason: null
authors:
- title: Adam Cogan
  url: https://ssw.com.au/people/adam-cogan
created: 2015-04-28 05:09:19+00:00
createdBy: Joanna Feely
createdByEmail: JoannaFeely@ssw.com.au
guid: 8d59feea-03b4-4cfc-b26e-77b2655293d9
isArchived: false
redirects:
- accommodation-do-you-know-the-best-online-accommodation-websites
related:
- rule: public/uploads/rules/do-you-create-an-online-itinerary/rule.mdx
- rule: public/uploads/rules/use-qantas-bid-now-upgrades/rule.mdx
- rule: public/uploads/rules/do-you-know-how-to-get-the-most-out-of-your-credit-card/rule.mdx
- rule: public/uploads/rules/do-you-check-your-boarding-pass/rule.mdx
- rule: public/uploads/rules/do-you-take-advantage-of-business-rewards-programs/rule.mdx
seoDescription: Compare hotel prices using online platforms like lastminute.com.au
  and stayz.com.au, then book directly with the hotel to potentially save hundreds.
title: Accommodation - Do you know the best online accommodation websites?
categories:
  - category: categories/company-operations/rules-to-better-travel.mdx
type: rule
uri: do-you-know-the-best-online-accommodation-websites
---

Figure: Example or Rule frontmatter

8. Add the text of your rule in markdown. You can also include MDX components (e.g. <emailEmbed/>, <youTubeEmbed />, etc.). 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.

9. Add the new rule to the category index

After you add a category to your rule.mdx, you also need to add the rule to the category file’s index list. The category page uses this list to know which rules belong to it.

Follow these steps:

1. Open the category file referenced in your rule (the path listed under categories:), for example:
   categories/company-operations/rules-to-better-travel.mdx

2. In the frontmatter of the category file, find the index: section.

3. Add your new rule to the list using its full rule path:

index:
  - rule: public/uploads/rules/existing-rule/rule.mdx
  - rule: public/uploads/rules/{{rule-uri}}/rule.mdx

10. Merge your changes, see Merging Your Fork

Next Step

See How to Add and Edit Categories and Top Categories