How to Add and Edit Categories and Top Categories - SSWConsulting/SSW.Rules.Content GitHub Wiki

Make Changes via TinaCMS UI

Add a new category

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

Figure: New Rule button.

  1. Open the Category collection, you will see a list of top_categories

  1. Select the top category where you want to create or edit a category

  2. Click "Create New" | Category

  1. Fill out the form

  2. Click Save when you’re done, you will then be guided to create a new branch for your changes

  3. If you created a new category, don’t forget to add it to a Top Category: Open the Categories collection | Find the top category you want to assign your new category to | Click to Edit | Find the Categories field | Click Add | Click Unselected Category | Choose the category you want to assign

  1. 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?)

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

Reorder an existing category

  1. Open the Category collection, you will see a list of top_categories

  1. Select the top category you want to reorder

  2. Find the file named index

  1. Drag items in the list to change their order
  1. Click Save to apply your changes

Make Changes via GitHub

Important

Adding and Editing Categories and Top Categories should be done via merging a forked repository. If you have not set one up, follow the instructions under "Fork the repository (One-time setup)" in Editing with Forks

Categories

It is useful to group rules into categories, for better perusal!

Add a rule to an existing category

Follow these steps:

  1. Go to the category index public page (E.g. https://ssw.com.au/rules/rules-to-better-communication)
  2. Click on 'edit in GitHub'
  3. Click on the little pencil to edit the Markdown file
  4. Add a new rule URI to the "index" list, in the desired position

Reorder an existing category

Follow the same steps 1-3 above, then update the list order by moving items around as needed.

---
type: category
title: Rules to Better Communication
guid: 471816bf-f0df-4835-bf4d-66a90f6f1adc
uri: rules-to-better-communication
experts: https://www.ssw.com.au/people/?skill=Scrum
consulting: https://www.ssw.com.au/consulting/scrum
index:
- some-rule
- another-rule
- some-other-rule
- a-fourth-rule
---
This is a summary for the category

Add a new category

If you think SSW.Rules need a whole new category for one or more rule, follow these steps to create it:

  1. Go to your forked repository.
  2. Decide on which Top Category your Category should belong to.
  3. Open the categories/{top-category name} (e.g. categories/Communication) folder.
  4. Click Add file | Create new file
  5. Name your file {category name}.mdx (e.g. 'rules-to-better-communication.mdx').
  6. In the your {category name}.mdx file, you need to add the following fields in the frontmatter
  7. You can also add a summary for the category after the frontmatter.
  8. Important: In the index.mdx file of the top category, add your category URI to the list of categories under index:

Frontmatter and summary example:

---
_template: category
type: category
title: Rules to Better Communication
guid: 471816bf-f0df-4835-bf4d-66a90f6f1adc
uri: rules-to-better-communication
experts: https://www.ssw.com.au/people/?skill=Scrum
consulting: https://www.ssw.com.au/consulting/scrum
index:
  - rule: public/uploads/rules/follow-up-effectively/rule.mdx
  - rule: public/uploads/rules/warn-then-call/rule.mdx
  - rule: public/uploads/rules/keep-tasks-handy-for-calls/rule.mdx
---
This is a summary for the category

Figure: Frontmatter example for a category

Tip: Don't add a new line after the front matter as this has caused issues in the past.

Edit a category

If you need to edit a category, follow these steps:

  1. Go to your forked repository.
  2. Find the category you want to edit under categories | {your category's top-category} | {your category}.mdx
  3. Click on the pencil button.
  4. Make the changes you want.
  5. Merge your changes, see Merging Your Fork

For the SSW.Rules markdown syntax, read the sample page

WARNING: Do not leave categories empty.

Top Categories

A top category is a group of categories that are related!

Add a top-category

If you think rules could have a new top-category, follow these steps:

  1. Go to your forked repository
  2. Open the categories folder
  3. Click Add file | Create new file
  4. Name your file {top-category name}/index.mdx (e.g, 'software-development/index.mdx')
  5. Edit the index.mdx file, and add the following fields in the frontmatter
    • _template: value must be set to top-category
    • type: value must be set to top-category
    • title: the title of the top-category, this will be display on the home page (e.g Software Development)
    • uri: the URI for the new category (e.g. software-development)
    • index: A markdown list of categories URI composing the top-category

Example top category:

---
_template: top-category
type: top-category
title: Software Development
uri: software-development
index:
- rule: public/uploads/rules/do-you-know-the-best-way-to-demo-microsoft-crm-to-clients/rule.mdx
- rule: public/uploads/rules/identify-crm-web-servers-by-colors/rule.mdx
- rule: public/uploads/rules/do-you-know-how-to-correctly-use-the-terms-configuration-customization-and-extending-in-the-crm-context/rule.mdx
- rule: public/uploads/rules/installation-do-you-turn-on-development-errors-and-platform-tracing/rule.mdx
---

Figure: Frontmatter example for a top-category

Edit a top-category

To edit a top-category, follow these steps:

  1. Go to your forked repository
  2. Open the folder categories | {top-category name}
  3. Open the index.mdx file
  4. Click on the pencil to edit
  5. Make the changes you want
  6. Merge your changes, see Merging Your Fork