This is an example rule + markdown cheatsheet to show you the things you can use to format an SSW rule.

1. Headings, paragraphs, and blockquotes

# This is a heading 1
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.

Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborumsunt in culpa qui officia.

## This is a heading 2
### 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 Title

Figure: Markdown to generate headings and blockquotes

This is a heading 1

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

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 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 &lt;mark&gt; (HTML needed)

Figure: Markdown to generate different text styles

This text will be italic
This will also be italic

This text will be bold
This will also be bold

strikethrough

You can combine them

These words 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 another

Figure: Markdown to generate 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 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.

---

5. Boxes

::: greybox  
This is a box using the class "greybox".  
:::

Figure: Markdown to generate boxes

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  
![caption](image-file.jpg)
:::

---

7. Captions

::: bad  
Figure: Caption for bad examples 
:::

::: ok  
Figure: Caption for OK examples 
:::

::: good  
Figure: Caption for good examples 
:::

Captions on images

Captions on boxes

Figure: Caption for normal 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!

Video: 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`

Do you understand a data type change = "Data Motion Scripts"? http://bit.ly/9OMKTO #ssw #sswrules

— Martin Hinshelwood 🏴󠁧󠁢󠁳󠁣󠁴󠁿 🇪🇺 🇲🇽 (@MrHinsh) September 10, 2010

---

10. 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

---

11. Code

This is a piece of code in a code block

Learn more on Markdown – Do you set the language on code blocks?

See this json file for all supported languages and their aliases we can use in Rules. See below for 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

#include <iostream>
using namespace std;

int main() 
{    
    cout << "Size of char: " << sizeof(char) << " byte" << endl;
    cout << "Size of int: " << sizeof(int) << " bytes" << endl;
    cout << "Size of float: " << sizeof(float) << " bytes" << endl;
    cout << "Size of double: " << sizeof(double) << " bytes" << endl;

    return 0;
}

Figure: C++ 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

---

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

---

---

---

It doesn’t matter what type of information you have, suffering a data loss is frustrating and takes time and money to restore and recover.

Whenever you have to delete content, take an extra step and and paste it into an email thread as a safety step. You should also inform people that care about that content.

This way it's easy for others to see what was removed, and put it back if necessary.

Every time you decide that a process should be documented, it’s important to double check that the content does not already exist.

Spending 5 minutes Googling can save you a lot of clean up and maintenance later.

Figure: You should think twice before adding content. As a great Australian Kerry Packer once said: "If you want to pass a new law, why don't you do it only when you've repealed an old one?"

When writing any content it is vital you cut unnecessary words to keep the reader interested and focused. This is especially important for dense or technical documentation.Your writing can be less wordy and still get the message across.

Improve your content and ask - how many words don't provide value or clarity?

Clear communication is essential for success, and especially helpful in professional or technical contexts. You should make your content more visually interesting and easier to scan quickly. Lists and emojis are great tools to achieve that.

Lists are great to make texts easier to digest. Emojis makes it even easier to consume when a lot of information is present. By using them you can enhance the communication experience. But when repeated excessively, they can become a hindrance rather than a help.

When there are multiple items listed, it can be challenging to distinguish between them quickly, leading to confusion and miscommunication. If the same emoji is repeated multiple times within a list, it can create visual clutter and make the list more difficult to read. Following the DRY principle by avoiding excessive repetition of emojis helps to create lists that are visually interesting and easy to read, while also promoting efficient and maintainable content creation.

By avoiding repeated emojis within each category, the list remains clear and concise, which can improve communication and understanding. Thus making it easy to scan the list and understand the benefits and drawbacks of a particular situation.

Tip: When creating a list that includes emojis, avoid repeating the same emoji more than 3 times within the list. This helps to keep the list concise, readable, and consistent while still allowing for some repetition for emphasis or clarity.

This is also valid for words in lists. You should keep only the part that is unique in each list item.

A picture says a thousand words, so using screenshots to provide context is invaluable. However, it isn't always clear to others what part of the screenshot they need to be looking at. So, it is important that you edit your screenshots to add extra info such as highlighting critical information.

Windows provides a default tool for taking and editing screenshots called the Snipping Tool. However, it is quite limited in functionality. For example, it doesn't provide the ability to draw a neat rectangular box quickly and easily.

There are heaps of great tools that provide much more advanced functionality. The best tools are

Source: Google Trends

You should always use discretion in your public documentation. Hide any sensitive information, like your clients’ names, from screenshots and general documentation.

Imagine you're browsing a website. You come across an area on the page that seems oddly blank, only to realize it's a white image blending seamlessly into the white background. This disrupts the browsing experience. So how do you prevent that?

The Importance of Image Borders

Making your images distinct is a key part of creating a user-friendly website. You should add borders to images, especially those with a white or light-colored background.

• Visibility: A border makes the image stand out, even if the website's background color matches the image's color.
• Professionalism: Borders can add a sense of completeness to your site's design.

We've all missed a piece of a message and found out later that we'd got it wrong. This can lead to miscommunication, mistakes, and lost time. Even worse, when finding out later that someone has misread something, there can be a lot of work to fix! But, there are ways to prevent this. Do these things to always make your writing clear:

An important case - don't let anybody skim over negation and misinterpret your message:

When highlighting items (file names, user commands etc.) be sure to:

1. Distinguish the items from the rest of the surrounding text; and
2. Be consistent

Use the following rules to highlight items in your document:

Style	Use this style on	Example
Bold text	Menus, commands, dialog box options, file names and paths	To access the application, click Start | Programs | Accessories | System Tools | Disk Defragmenter
Initial Capitals + Bold	File paths and file names	Now open C:\My Documents\Invoice.doc.
Different colour styling	Web UI - Important words on headings	Want to build an Angular application?
UPPER CASE	Code keywords and database elements	Use the INNER JOIN clause in SQL Server to join one table to another.
Monospace (Courier New font)	Code samples, error messages	You will see the following error: error opening database: database is currently in use.

Email templates are an awesome way to help people save time writing emails. Often the template needs to indicate a piece of text that should be replaced with custom content. When you need to identify text that should be replaced (e.g. in an email template), it's important to use a consistent way of indicating the replaceable text with a placeholder.

Use a consistent character to make it clear which piece of text should be substituted.

Video: Choose the Best Text Placeholders (3 min)

However, everyone has their own preferences about which placeholder character to use 🥸

For example:

• SSW Rules historically used xxx
• SSW Intranet | Sales templates use ❌❌❌
• SSW GitHub Sprint Templates use ✏️xxx
• SQL developers are used to [ ]
• Word Mail Merge users are used to « »
• API and React developers are used to { }
• Angular developers are used to {{ }}
• Visual Studio code reviewers are used to TODO:

Let's see these in action:

• The quick brown fox xxx over the lazy dog
• The quick brown fox ❌❌❌ over the lazy dog
• The quick brown fox ✏️xxx over the lazy dog
• The quick brown fox [ action ] over the lazy dog
• The quick brown fox « action » over the lazy dog
• The quick brown fox { action } over the lazy dog
• The quick brown fox {{ action }} over the lazy dog
• The quick brown fox {{ ACTION }} over the lazy dog (currently the standard in SugarLearning and SSW Rules)
• The quick brown fox TODO:action over the lazy dog

More info on the origins

[] are commonly used to label things. On sensitive emails, the text [Sec: Official] gets appended or prefixed to the subject, for example.

Using [] for replaceable text can be confusing since there is already the common usage for labelling.

{ } are used frequently in popular APIs like Microsoft Graph, Microsoft PowerPlatform Facebook, Riot, Amazon and also in React

Angular interpolation uses {{ and }} as a delimiter. They indicate a variable and we think this is a very clear way to indicate that something needs to be replaced because it is very uncommon to see this syntax outside of Angular code.

So, double curly brackets are recommended instead of square brackets to indicate replaceable text.

In certain places such as Sales templates, you cannot afford to miss a single placeholder

Of course, if you want to make it even more obvious then highlight the text in yellow... however you can't do it in many places like Microsoft Forms... so another option is to use an emoji like the ✏️ or to make it super obvious the three ❌❌❌

Another way to draw attention to text is to make the placeholder all caps.

Replaceable text is often seen in email templates:

When you add a quotation, put them in a new line with an indent.

You should always indent any quotes that you use on a new line.

Whenever writing numbers, it's generally a good idea to use numerals, especially for complicated numbers. Numerals are more easily noticed when a page is scanned by a user's eye.

For example:

Remember to use dividers when referring to large sums or phone numbers.

Use a consistent format when writing addresses.

The structure should follow: Number, Street Name, City, State (abbreviation) Postal Code, Country

• Beware of the commas positioning (inexisting between State and Postal Code)
• Don't use dashes, slashes, or bars to separate the elements (OK if it is in the Street Name part)
• Country is not always necessary depending on the audience
• If you have enough space, it is OK to write it in 2 lines
• We're in Australia and this should work for most countries' addresses, but some specific locations might have different address structures that won't allow following this rule

We know that the way your inbound links are worded does make a difference. They play an important factor for search engine results and for the users.

Having descriptive links with relevant words improves your website SEO and gives a more friendly experience to users.

For example, if a website had millions of inbound links that described it as "Movies for Free", when someone searches for "free movies" on Google, it would point to this website.

So what does this mean? All those links that are pointing to pages on your website displayed as 'More', 'Link', 'This' or 'Click Here' aren't doing you any favors when it comes to increasing your Google rankings.

Also, if you make your the link the entire URL, it won't be very readable to users. You should replace it with a descriptive sentence using relevant words.

When you’re sending emails, or pinging someone in Teams, your URLs should be as clean as possible. Having no extra noise ensures that they are easy to read, and it is more aesthetically pleasing. It is also a good idea to break a line before an URL, improving its readability.

Presentations

For presentations, it's especially important to keep URLs cleaner. Remember to always remove https://www. from links in your presentations. It keeps the slides cleaner and more readable.

It's important to use correct capitalization when writing titles/headings for web content. For main titles, you should capitalize the first word, all nouns, all verbs (even short ones, like "is"), all adjectives, and all proper nouns. Leave subtitles in normal sentence form.

You can find more rules & tips on capitalizing here:

How to Capitalize Titles and Headings Correctly

It's best to only do this on main titles, and leave subtitles in normal sentence form - only capitalize the first word and proper nouns. Basically, it saves hassles... English is a confusing language, and there are too many variations that cause too many arguments.

With so many different capitalization conventions used in technology names, it can be confusing to know which convention to use for which technology.

The main 5 types used are:

1. All uppercase – ALL UPPERCASE
2. All lower case – all lowercase
3. Pascal case - PascalCase
4. Camel case – camelCase
5. Only first letter capitalized - Onlythefirstletter

Here’s a quick overview:

• .NET - All uppercase
• DevOps - Pascal case
• JavaScript - Pascal case
• jQuery - Camel case
• Angular (previously AngularJS) - Only first letter capitalized
• SharePoint - Pascal case
• email - All lowercase
• MVC - All uppercase
• CRM - All uppercase
• SAP - All uppercase
• Salesforce - Only first letter capitalized
• gulp - All lowercase
• Agile - Only first letter capitalized
• Scrum - Only first letter capitalized (Note: Scrum is not an acronym, so it should never be spelled "SCRUM") |

According to the Scrum Alliance, "Scrum" is capitalized.

You will occasionally see it written incorrectly:

❌ scrum - Not capitalized

❌ SCRUM - All caps (incorrect, as Scrum is not an acronym)

Other Scrum terms should also be capitalized:

• Sprint
• Product Owner
• Scrum Master
• Product Backlog
• Sprint Review
• Sprint Planning
• Sprint Retrospective

Improper spelling, grammar, and punctuation gives a bad impression of your company and can result in your message not being conveyed correctly. Emails with no full stops or commas are difficult to read and can sometimes even change the meaning of the text. And, if your program has a spelling checking option, why not use it?

Web Content

When on a web page, install Grammarly Addon for Chrome so you can automatically check web content. For example, while editing in a CMS.

Any other text can be checked manually. Go to Grammarly, create a New Document and Paste your content to check your text.

Documents

On Word, press F7 (or on the ribbon go to Review > Spelling & Grammar ) to check your .docx text.

Presentations

On PowerPoint, press F7 (or on the ribbon go to Review | Spelling & Grammar ) to check your .pptx text.

You should also keep "Check grammar with spelling" checked in your PowerPoint Options | Proofing:

Attention to detail plays a vital role to effective communication. Spelling and syntax errors, 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 "aka" not "a.k.a"

  Note: Although Wikipedia considers multiple ways to spell the acronym for "also known as", the convention is simply "aka" - All letters are in lowercase and letters are 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")

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 essential for effective communication. Spelling and syntax errors may appear trivial, but 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. Language precision is a valuable skill in our diverse and dynamic communication landscape.

Acronyms are a common way to shorten words or phrases, but they can often lead to confusion and misunderstandings, especially for those new to a particular field or industry. To ensure clear communication, it is best to avoid acronyms whenever possible and use the full name of the term or phrase instead.

1. Avoid acronyms whenever possible. Use the full name of the term or phrase instead.
2. Especially, avoid using acronyms in titles, headings, and other prominent places. This can make it hard for readers to understand the content.
3. If you must use an acronym, define it the first time you use it in your writing.
4. If you must use acronyms, be consistent. If you use an acronym for a term or phrase, use it consistently throughout your writing.

By avoiding acronyms and using the full names of the terms or phrases, the message is easier to understand.

Well-known acronyms that we commonly use (FYI, URL, HTTPS, GIF, etc.) are more acceptable and safe to use.

When explaining steps in a process. For example, for printing a file, make sure to say something "will" happen or is happening. This is especially important when describing your own software, because saying something "should" happen implies that it may or may not happen (there could be bugs!).

In order to connect (with a username and password) to:

• A Winforms application, you "log in"
• A Webforms application, you "sign in"
• A PC, Server or Domain, you "log on"

See the Login From Wikipedia.

They are similar but "Retry" is a more like computer jargon, whereas "Try again" sounds friendlier and more human.

When writing any documentation it is important to put only one space after commas or other punctuation. This makes the document easy to read and looks more professional. For example:

Use lowercase after "-" in a text.

When writing technical documentation, one of your primary objectives is to ensure the document is written consistently to ensure a flowing reading experience. Ensure the reader and author are correctly referenced throughout your document.

The first example is bad because it confuses the reader as to whom the author is referring.

It is occasionally acceptable to use the first person, "we", "I", "us", "our" etc.
An example of an acceptable use of first person is: "We recommend that you backup your database first." However, you must never use the first person to refer to the reader.

An important area to apply strict standards to is documenting instructions. The way in which instructions are worded and arranged is very important in helping the user understand the instructions. Therefore, the instructions should be minimalistic, clear and concise.

We often see documentation like: '...then you click on Select All Programs from the Start menu'. This is bad! You should keep it simple and always list the items in the order the user selects them.

Be sure you keep the operations clearly in the right order:

If you follow this rule, users won't be confused.

It's usually easier for users to remember where given information is when it is associated with an image/icon. This is especially true for non-technical people or the ones that are not very familiar with digital workspaces.

An easy and fun way to alleviate this issue and boost user adoption to Microsoft Teams is to use Emojis in your channel names (using Windows Key + .)!

Tip: Always remember to add a space between the emoji and text, for better readability.

Sometimes when writing content, you need to make the decision to keep it on the same line or put it on a new line.

It is recommended that notes, tips and figures should be on a new line to enable better readability. It can also be beneficial to bold those words.

This is also recommended when sending URLs for readability.

See the Markdown Guide for more information on line breaks.

Quotation marks can help user distinguish controls from the normal words. This is especially important in technical documentation, as the control names can be normal words.

It is a good idea to create a dummy company to represent all clients on internal/external documentation, including a made-up name for the person behind that company.

For example, anytime you need to show a scenario of dealing with clients, use the made-up company called "Northwind" which is managed by the also made-up client "Mr. Bob Northwind", often referred to as just "Bob".

Most of documentation starts from a real-world situation, but you don't want to expose real clients' names.

Readability of URLs is important, so you should consider making a short URL. However, it is not just making the length as short as possible - it should be friendly.

If you use a unfriendly and long link people can't see what they are clicking through to. In fact, this is what most spammers rely on.

Sometimes even a nice URL can be improved by removing all the filler words and just keep the main keywords. This way your URL's are more friendly. Also, make sure your main keywords are relevant for searches.

Bit.ly

Sometimes you are not in control of the link. In those cases, use Bitly to transform any long URL into a shorter, more readable link.

When have a Bitly account, you can customize links to a more readable option.

When naming documents and images, use descriptive words and kebab-case (where you separate words with hyphens) to make your files more easily discoverable.

✅ Choose the right words

The file name and its title is regarded more highly by search than the content within documents. Also, the file name is what is displayed in search results, so by making it descriptive you are making it easier for people to identify the purpose of your document.

Once you have chosen the best words, make it readable and consistent in formatting:

❌ Avoid spaces

As far as search goes, using spaces is actually a usable option. What makes spaces less-preferable is the fact that the URL to this document will have those spaces escaped with the sequence %20. E.g. sharepoint/site/library/Monthly%20Report.docx. URLs with escaped spaces are longer and less human-readable.

Know more on Do you remove spaces from your folders and filename?

❌ Avoid CamelCase

This is a popular way to combine words as a convention in variable declarations in many coding languages, but shouldn't be used in document names as it is harder to read. Also, a file name without spaces means that the search engine doesn't know where one word ends and the other one begins. This means that searching for 'monthly' or 'report' might not find this document.

❌ Avoid Snake_Case

Underscores are not valid word separators for search in SharePoint, and not recommended by others. Also, sometimes underscores are less visible to users, for example, when a hyperlink is underlined. When reading a hyperlink that is underlined, it is often possible for the user to be mistaken by thinking that the URL contains spaces instead of underscores. For these reasons it is best to avoid their use in file names and titles.

✅ Use kebab-case

A hyphen (or dash) is the best choice, because it is understood both by humans and all versions of SharePoint search.

Extra

• Add relevant metadata where possible

If a document library is configured with metadata fields, add as much relevant information as you can. Metadata is more highly regarded by search than the contents within documents, so by adding relevant terms to a documents metadata, you will almost certainly have a positive effect on the relevance of search results.

• Ensure filenames are unique when tracking files with Git

Within a team, there may be a mix of operating systems being used by its members. For users on MacOS or other OS's that have case-sensitive filenames, it's crucial to ensure that filenames are unique. For example, don't use 'File.txt' if 'file.txt' already exists. This is especially important if these files are being tracked with Git, as it can cause issues for users on Windows, which has case-insensitive filenames.

It is very important to have your Word, PowerPoint, PDFs, and design documents up-to-date. You should also make it easy for anyone to identify which version they are looking at. The most effective way to achieve this is by placing the version number on the right-hand side of the footer.

See how you increase the version number:

• Major 1.0 - Rarely change - only with major upgrades. E.g. Complete redesign
• Minor 1.1 - New features / release (customer facing) E.g. Add/remove a heading or a section
• Revision 1.11 - Emergency maintenance, spelling fixes

File names

It is also good practice to include the major version number in the name of the files. This helps navigating through the old and the new versions, and makes it easy to roll back any changes and use an older version.

It is not a good idea to have spaces in a folder or file name as they don't translate to URLs very well and can even cause technical problems.

Instead of using spaces, we recommend:

• kebab-case - using dashes between words

Other not recommended options include:

• CamelCase - using the first letter of each word in uppercase and the rest of the word in lowercase
• snake_case - using underscores between words

For further information, read Do you know how to name documents?

This rule should apply to any file or folder that is on the web. This includes Azure DevOps Team Project names and SharePoint Pages.

Often while doing a task, you follow a process. If it's a repeatable task, it's important that the process is documented and up-to-date. Otherwise, the next person to do the task won't know the right thing to do. The job is not done until it's documented - documenting/updating a standard is part of the "Definition of Done" in such tasks.

When should you do it?

Document or update a process as soon as a change happens. Don't wait until the task is complete because it will likely be forgotten.

Say a meeting where multiple options were discussed and a decision was made. You must communicate the client and the team, but before sending a 'Done', make sure the decision and its reasons are documented and accessible by others who didn't attend the meeting (e.g. Create or update a rule). This way others may not need a meeting next time.

If you are really under the crunch and your task is critically urgent (e.g. Production website is down), then send yourself an email to action the standard update later.

Where should you do it?

Processes are usually stored in different places depending on the context they apply to.

• Wiki or Repo - If related to a project
• PBIs - If related to a task being worked on
• Rules or blogs - Public standards and best practices
• Intranet - Internal standards
• Induction (e.g. SugarLearning) - Links to standards/rules + test knowledge

Developer Documentation

Developer documentation is stored close to the code. Examples are GitHub wiki and Azure DevOps wiki.

End-User Documentation

Option 1: Word document

Option 2: Plain HTML pages

Option 3: GitBook.com (recommended)

Architectural Decision Records (ADRs) are lightweight documents use to record important decisions in your project. They do not necessarily have to be related to architecture, but could be any important decision made by the team.

What are the dangers of not documenting important decisions?

1. Lack of transparency and communication
2. Loss of intellectual property
3. Loss of historical context
4. Risk of repeating mistakes
5. Difficulty in auditing and governance

What are the advantages of using ADRs?

1. Providing documentation and historical context
2. Collaboration and communication
3. Informed Decision making
4. Decision re-evaluation
5. Avoiding blind acceptance or reversal

The act of documenting an important decision, forces developers to think more objectively about their decision. If the decision is likely to cause contention it may be quicker to document it via an ADR and get feedback, than it would be to implement the change and let the reviewer try to infer your reasoning.

Additionally, documenting decision 'deciders' ensures that we have a 2nd pair of eyes across the decision, just like we do with the checked by rule, test please rule, and pull-requests.

ADRs can also help with knowledge sharing across teams, as other Solution Architects will have access to a succinct explanation of the problem and the decided solution.

Another benefit is that future developers joining the project now have access to the historical context as to why certain decisions were made.

Where should ADRs be stored?

They should be stored wherever the technical documentation for your project lives. Storing them in Git along with your code works well, but alternatively wherever your technical documentation lives (i.e. a wiki).

What Can I use to Create and Manage ADRs?

There are several tools available to help create and managed ADRs, but one of the best ones is Log4Brains. Log4Brains can help to create and view ADRs.

This can be installed by running:

npm install -g log4brains

You can then initialize your git repo by running:

log4brains init

Which will guide you through a simple setup process.

To create a new ADR, run:

log4brains adr new

Lastly, to preview your ADRs, run:

log4brains preview

You can see an example of ADRs with log4brains in action on our SSW.CleanArchitecture template.

Related Articles

• Dan Does Code - Demystifying Architectural Decision Records Why Every Project Needs Them

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, that category is completely missing.

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

A standard computer keyboard can produce dozens of different symbols. Some of these are commonly used, whereas others are used only rarely. It is important to know what each symbol is called and how to spell it in English. That way, if you are uncertain of how or when to use a particular symbol, you can look it up and get your answer. Below is a table of common keyboard symbols and their spellings. 

| Symbol| Explanation | | --- | --- | | ` | Accent grave | | --- | --- | | ~ | Tilde | | --- | --- | | ! (Shift + 1) | Exclamation mark | | --- | --- | | @ (Shift + 2) | At symbol | | --- | --- | | # (Shift + 3) | Hash | | --- | --- | | $ (Shift + 4) | Dollar sign | | --- | --- | | % (Shift + 5) | Percent | | --- | --- | | ^ (Shift + 6) | Caret | | --- | --- | | & (Shift + 7) | Ampersand | | --- | --- | | * (Shift + 8) | Multiplication | | --- | --- | | ( (Shift + 9) | Left parenthesis | | --- | --- | | ) (Shift + 0) | Right parenthesis | | --- | --- | | - | Dash | | --- | --- | | _ (Shift + -) | Underscore | | --- | --- | | = | Equal | | --- | --- | | + (Shift + =) | Plus | | --- | --- | | [ | Left bracket | | --- | --- | | ] | Right bracket  | | --- | --- | | { (Shift + [) | Left brace | | --- | --- | | } (Shift + ]) | Right brace | | --- | --- | |
| Backslash | | --- | --- | | | (Shift + ) | Vertical bar | | --- | --- | | ; | Semicolon | | --- | --- | | : (Shift + ;) | Colon | | --- | --- | | ' | Single quote | | --- | --- | | " (Shift + ') | Quote | | --- | --- | | , | Comma | | --- | --- | | . | Dot | | --- | --- | | < (Shift + ,) | Less than | | --- | --- | | > (Shift + .) | Greater than | | --- | --- | | / | Forward slash | | --- | --- | | ? (Shift + /) | Question mark | | --- | --- |

Have you ever stumbled upon a useful chart, diagram, or infographic with embedded text, only to find that the text can't be copied? This is incredibly frustrating because the information is locked in an image format. The process of manually typing out the text can be time-consuming and prone to errors. There are a couple ways to solve this:

Method 1: Using OneNote

Using OneNote is simple. All you do is paste your image into OneNote, right click on it, and click Copy Text from Picture.

Method 2: Using Google Drive

In Google Drive you need to upload your image as a new file. Then you need to right click on the image file and select ** Open with | Google Docs**.