Rules to Better Technical Documentation - 4 Rules
This is an example rule + Markdown cheatsheet to give you some guidance around how to write rules and show you the things you can use to format an SSW rule.
Concepts to write rules
There are a few concepts that are applied to structure most SSW Rules:
- Show the pain - Usually in the intro, explain the problem and context around why that rule exists
- Give good and bad examples - Include practical examples for people to better understand the concepts. Using images is usually the best way to go
- Explain the why, not the how - A rule isn't a place to document how to use a 3rd party product. You should focus on the reasons why we do something, and then link to external documentation on how to do something
See a few examples of SSW Rules that follow the structure of good and bad examples, then link off to external documentation for more information:
1. Headings, paragraphs, and blockquotes
## This is a heading 2 (We never use heading 1 in SSW Rules Content to improve SEO, that's because the title is already a heading 1) ### This is a heading 3 #### This is a heading 4 ##### This is a heading 5 ###### This is a heading 6 and below is a blockquote \> \*Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante. \> \- Someone famous in Source TitleFigure: Markdown to generate headings and blockquotes
::: info Do not use heading 1 content - the title is already a heading 1, and we should avoid using multiple
<h1>elements on one page. :::This is a heading 2
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
This is a heading 2 with some emphasized text by making it bold
Tip: See text decoration section for more details on making the text bold.
This is a heading 3
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
This is a heading 4
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
This is a heading 5
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
This is a heading 6
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
...and this is a blockquote:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.
> * Someone famous in Source Title
---
2. Text decorations
_This text will be italic_ _This will also be italic_ **This text will be bold** **This will also be bold** _You **can** combine them_ \~\~strikethrough\~\~ <mark>These words</mark> are surrounded by a <mark> (HTML needed)Figure: Markdown to generate different text styles
This text will be italic
This will also be italicThis text will be bold
This will also be bold~~strikethrough~~
You can combine them
<mark>These words</mark> are surrounded by a <mark> (HTML needed)
---
3. Lists
#### Unordered lists - This is the first item of an unordered list - This is the second item of an unordered list 1. This is the first item of an ordered list inside an unordered list 2. This is the second item of an ordered list inside an unordered list - This is the third item of an unordered list - This is the first item of an unordered list inside another - This is the second item of an unordered list inside another 1. This is the first item of an ordered list inside a nested unordered list 2. This is the second item of an ordered list inside a nested unordered list #### Ordered lists 1. This is the first item of an ordered list 2. This is the second item of an ordered list 3. This is the third item of an ordered list - This is the first item of an unordered list inside an ordered list - This is the second item of an unordered list inside an ordered list 1. This is the first item of an ordered list inside another 2. This is the second item of an ordered list inside anotherFigure: Markdown to generate lists
Unordered lists
- This is the first item of an unordered list
- This is the second item of an unordered list
- This is the first item of an ordered list inside an unordered list
- This is the second item of an ordered list inside an unordered list
- This is the third item of an unordered list
- This is the first item of an unordered list inside another
- This is the second item of an unordered list inside another
- This is the first item of an ordered list inside a nested unordered list
- This is the second item of an ordered list inside a nested unordered list
Ordered lists
- This is the first item of an ordered list
- This is the second item of an ordered list
- This is the third item of an ordered list
- This is the first item of an unordered list inside an ordered list
- This is the second item of an unordered list inside an ordered list
- This is the first item of an ordered list inside another
- This is the second item of an ordered list inside another
---
4. Links
[link text](https://www.url.com "link title")Figure: Markdown to generate links
This is an internal link.
This is an internal link with title (hover me).
This is an external link.
::: greybox Cool link features:
- We use icons on files' links to not to surprise users
- Our main headings auto-generated anchor links so users can easily access a section of a long page like this one. E.g. To go straight to this section of the page, you can access https://ssw.com.au/rules/rule/#4-links
:::
---
5. Boxes
::: greybox This is a box using the class "greybox". :::Figure: Markdown to generate boxes
::: greybox
This is a box using the class "greybox".
:::::: highlight
This is a box using the class "highlight". :::::: highlight
This is an example of a heading in a highlight
:::
::: info
This is a <div> using the class "info". Works the same as using a <p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation.
:::::: info
This is an example of a heading in a info
:::
::: china
This is a <div> using the class "china". Works the same as using a <p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
:::::: china
This is an example of a heading in a china
:::
::: codeauditor This is a <div> using the class "codeauditor". Works the same as using a <p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
:::::: codeauditor
This is an example of a heading in a codeauditor
:::
::: todo
This is a <div> using the class "todo". Works the same as using a <p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco.
:::Hiding content
Use the class "hidden" to hide content.
::: hidden bfb265e3-644e-4cbe-b17c-4d378b014809-7947936 :::Figure: Nothing will show up from this Markdown
---
6. Images
::: img-small \ :::::: img-small
!Figure: Image using class "img-small" :::::: img-medium
!Figure: Image using class "img-medium" :::::: img-large
!Figure: Image using class "img-large" :::::: no-border !Figure: Image without border :::
!Figure: ..and with a short caption
::: todo
TODO: Make these images hosted internally as per Do you make sure your images are hosted internally? :::---
7. Captions
::: bad Figure: Caption for bad examples ::: ::: ok Figure: Caption for OK examples ::: ::: good Figure: Caption for good examples :::Captions on images
::: bad
!Figure: Caption for bad images :::!Figure: Caption for regular images
::: ok
!Figure: Caption for OK images :::::: good
!Figure: Caption for good images :::Captions on boxes
::: greybox
This is an example of a bad grey box.
:::
::: bad
Figure: Caption for bad examples :::::: greybox
This is an example of a normal grey box. :::
Figure: Caption for normal examples::: greybox
This is an example of a OK grey box. :::
::: ok
Figure: Caption for ok examples
:::::: greybox
This is an example of a good grey box. :::
::: good
Figure: Caption for good examples
:::---
8. Videos
Code for videos
`youtube: https://www.youtube.com/embed/0ugMkda9IBw` **Video: Top 5 Reasons Why ASP.NET MVC is Great (3 min)**Figure: Markdown to add videos and video captions
Example
Check out this video - it's responsive!
youtube: https://www.youtube.com/embed/0ugMkda9IBwVideo: Top 5 Reasons Why ASP.NET MVC is Great (3 min)---
9. Twitter Cards Embed
Embedding a Tweet is similar to a video. Copy the link of the tweet then add it to the rule with backticks on each side like this:
`oembed: https://twitter.com/MrHinsh/status/24123713864`oembed: https://twitter.com/MrHinsh/status/24123713864---
10. Code
To include code block in Markdown, start with 3 backticks <code>```</code> on a new line, write or paste your code, and then end with 3 backticks on a new line.
For syntax highlighting in code blocks, add the language name right after the opening backticks. Learn more on Markdown – Do you set the language on code blocks?
To add inline code in Markdown, wrap the code snippet with single backticks. See
this textas inline code for example.This is a piece of code in a code block::: bad
Figure: Bad example - Because this code doesn't include the language used :::See this json file for all supported languages and their aliases we can use in SSW Rules. See some examples:
let iceCream = "chocolate"; if (iceCream === "chocolate") \{ alert("Yay, I love chocolate ice cream\!"); \} else \{ alert("Awwww, but chocolate is my favorite..."); \}Figure: Javascript code block
IF EXISTS (SELECT 1 FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE='BASE TABLE' AND TABLE_NAME='Employees' ) ALTER TABLE [dbo].[Employees]( …… ) ON [PRIMARY] ELSE CREATE TABLE [dbo].[Employees]( …… ) ON [PRIMARY]Figure: SQL code block
public class MyClass \{ public string myField = string.Empty; public MyClass() \{ \} public void MyMethod(int parameter1, string parameter2) \{ Console.WriteLine("First Parameter \{0\}, second parameter \{1\}", parameter1, parameter2); \} public int MyAutoImplementedProperty \{ get; set; \} private int myPropertyVar; public int MyProperty \{ get \{ return myPropertyVar; \} set \{ myPropertyVar = value; \} \} \}Figure: C Sharp code block
\{ "glossary": \{ "title": "example glossary", "GlossDiv": \{ "title": "S", "GlossList": \{ "GlossEntry": \{ "ID": "SGML", "SortAs": "SGML", "GlossTerm": "Standard Generalized Markup Language", "Acronym": "SGML", "Abbrev": "ISO 8879:1986", "GlossDef": \{ "para": "A meta-markup language, used to create markup languages such as DocBook.", "GlossSeeAlso": ["GML", "XML"] \}, "GlossSee": "markup" \} \} \} \} \}Figure: JSON code block
---
11. Email Templates
Code for email template
::: email-template | | | | \-\-\-\-\-\-\-\- | \-\-\- | | To: | XXX | | Cc: | YYY | | Bcc: | ZZZ | | Subject: | \{\{ EMAIL SUBJECT \}\} | ::: email-content ### Hi XXX, \{\{ EMAIL CONTENT \}\} ::: ::: ::: good Figure: Good example - Nice email template :::Figure: Markdown for email templates
::: email-template
| | | | -------- | ------------------- | | To: | XXX | | Cc: | YYY | | Bcc: | ZZZ | | Subject: | {{ EMAIL SUBJECT }} |
::: email-content
Hi XXX
{{ EMAIL CONTENT }}
:::
:::
::: good
Figure: Good example - Nice email template
:::---
12. Tables
Code for tables
| Tables | Are | Cool | | \-\-\-\-\-\-\-\-\-\-\-\-\- | :\-\-\-\-\-\-\-\-\-\-\-: | \-\-\-\-\-: | | col 3 is | right-aligned | \$1600 | | col 2 is | centered | \$12 | | zebra stripes | are neat | \$1 |Figure: Markdown to generate tables
Examples
| Tables | Are | Cool | | ------------- | :-----------: | -----: | | col 3 is | right-aligned | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 |
| Markdown | Less | Pretty | | -------- | --------- | ---------- | | Still |
renders| nicely | | 1 | 2 | 3 |---
13. Thematic breaks (horizontal rules)
Code for hr
\-\-\-Examples
---
The English language is really complex, and often during a discussion you don't know the context until you get midway through the sentence, or even the end of the sentence. This problem is particularly notable when you are browsing a page on Google, because you lack the context of the rest of the page.
For example, a page might have a category on a website, but when you look at it in Google results, that category may not be shown.
Incorporating a prefix into webpage titles enhances clarity and immediately provides valuable context for users.
At a bare minimum, the context should be completely fleshed out in the title of a page. However, the gold standard is to use prefixes.
Prefixes provide several benefits including:
- Skimming - Establishing context without having to read the full content
- Contextualizing - Priming the reader on the subject matter
- Finding - Helping the reader quickly jump to the right content in a list
- Grouping - Categorizing content together without the need for a complex bespoke solution
::: ok !OK example - The context is included in the title :::
::: good !Good example - The prefix very clearly identifies the subject in the title :::
Attention to detail plays a vital role to effective communication. Grammar, spelling, and/or syntax mistakes, though seemingly minor, can significantly affect the clarity and professionalism of your writing.
Common language pitfalls
Embracing the modern standard not only keeps your writing current but also ensures consistency in your communication.
- Use "email" not "e-mail" or "EMail"
- Use "cannot" not "can not"
- Use "website" not "web site"
- Use "username" not "user name"
- Use "taskbar" not "task bar"
- Use "OK" not "Ok" or "okay/Okay"
- Use "aka" not "AKA" or "a.k.a"
::: info Note: Although Wikipedia considers multiple ways to spell the acronym for "also known as", the convention is simply "aka" - with all letters in lowercase and not separated by dots/spaces. :::
Syntax changes the meaning of certain words
Often when writing technical documents, you will instruct the reader to 'set up' his PC or run a 'setup' file.
- "Setup" is a noun, basically meaning an 'arrangement'(e.g. "The software setup")
- "Set up" is a phrasal verb, most commonly meaning 'to establish something.' (e.g. "To set up a computer")
How can you remember this? Mentally replace "setup" or "set up" with "setting up". If the sentence still basically makes sense, use two words. If it doesn't, use the single word. For example, the sentence "...he is setting up the shop" makes sense. "The setting up was all wrong" does not.
Be careful with homophones
Words like “verses” and “versus” are homophones, meaning they are pronounced the same but have different spelling and different meanings. Always ensure you are using the correct word. If you're not, it won’t be picked up by spell checkers.
- “Verses” refers to lines of poetry or bible passages (e.g. "Matthew 5:41 is one of my favourite bible verses")
- “Versus” refers to 2 or more parties in opposition to one another, especially in sports or legal situations (e.g. "Floyd versus Mayweather")
::: info “Versus” can be shortened to “vs.”, which is common in sporting situations, or “v.”, which is the standard abbreviation for legal scenarios. :::
More examples
- "Their" shows possession (e.g. "It's their car")
- "There" indicates a place (e.g. "It's over there")
- "They're" is a contraction for "they are" (e.g. "They're going to the party")
- "Principal" can refer to a person who leads a school or organization or can mean the original sum of money (e.g. "The school principal is retiring" or "The principal amount of the loan")
- "Principle" refers to a fundamental truth, rule, or value (e.g. "Honesty is a guiding principle in their company")
- "Weather" relates to the state of the atmosphere (e.g. "The weather is sunny today")
- "Whether" is used to introduce choices or possibilities (e.g. "I'm uncertain whether to attend the meeting")
---
Language precision is a valuable skill and is essential for effective communication - they significantly impact how your writing is perceived.
By following these guidelines and staying current with language conventions, you can enhance the clarity, professionalism, and effectiveness of your communication.
Acronyms are a common way to shorten words or phrases, but using niche terms can lead to confusion and misunderstandings. It's important to avoid jargon, especially for those new to a particular field or industry. To ensure clear communication, avoid unfamiliar acronyms where possible and use the full term instead.
- Avoid niche acronyms to avoid confusion.
- Don't use acronyms in titles, headings, or other prominent places. This can make it hard for some readers to understand the content those headings describe.
- If you must use an uncommon acronym, clearly define it the first time you use it.
- Be consistent. If you use an acronym for a term or phrase, use it consistently throughout your content.
::: greybox Ash: I'm attending FBC next week.
Eddie: What is FBC? ::: ::: bad Bad example: This conversation is unclear as Eddie doesn't know FBC :::
::: greybox Ash: I'm attending FireBootCamp next week
Eddie: Awesome! ::: ::: good Good example: No acronyms, clear communication :::
::: greybox Ash: I'm attending FBC (FireBootCamp) next week. Would you like to come with me?
Eddie: Yeah! FBC sounds great. ::: ::: good Good example: Defined acronyms can be used, but be careful to not assume the other person is aware of the term if you don't know for sure :::
By avoiding unclear acronyms and using the full names of the terms or phrases, the message is easier to understand.
::: greybox NB: Track this. ::: ::: bad Bad example: NB is unclear and old-fashioned :::
::: greybox Note: Track this. ::: ::: good Good example: "Note" is more common and understandable :::
Well-known acronyms that we commonly see (FYI, URL, HTTPS, GIF, etc.) are more acceptable and safe to use.
