SSW Foursquare

Rules to Better Technical Documentation - 44 Rules

  1. Do you know all the cool stuff you can do on SSW Rules?

    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

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

    Cool features:


    5. Boxes

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

    Figure: Markdown to generate boxes

    This is a box using the class "greybox".

    This is a box using the class "highlight".

    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.

    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.

    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.

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

    Figure: Image using class "img-small"

    Figure: Image using class "img-medium"

    Figure: Image using class "img-large"

    Figure: Image without border

    Figure: How a smaller image (400px) works with long caption. Full screen on mobile, real width on larger screens

    Figure: ..and with a short caption

    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

    Figure: Caption for bad images

    Figure: Caption for regular images

    Figure: Caption for OK images

    Figure: Caption for good images

    Captions on boxes

    This is an example of a bad grey box.

    Figure: Caption for bad examples

    This is an example of a normal grey box.

    Figure: Caption for normal examples

    This is an example of a OK grey box.

    Figure: Caption for ok examples

    This is an example of a good grey box.

    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!

    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`


    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

    Figure: Good example - Nice email template


    11. Code

    This is a piece of code in a code block

    Figure: Bad example - Because this code doesn't include the language used

    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

    TablesAreCool
    col 3 isright-aligned$1600
    col 2 iscentered$12
    zebra stripesare neat$1
    MarkdownLessPretty
    Stillrendersnicely
    123

    13. Thematic breaks (horizontal rules)

    Code for hr

    ---
    ***
    ___

    Examples




  2. Do you take a safety step before you delete content?

    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.

    Note: This doesn't replace the necessity of having a backup.

  3. Do you avoid duplicating content?

    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?"

  4. Do you avoid using unnecessary words?

    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.

    Click the "Select" button

    Figure: Bad Example - Unnecessary words

    Click "Select"

    Good Example - Short and direct

    "Building Software that People Understand"

    Figure: Bad Example - Common filler word "that"

    "Building Software People Understand"

    Figure: Good Example - Remove filler words for a clearer message

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

  5. Do you show 'Bad' and 'Good' examples when giving instructions?

    The best way to emphasize your point is to show the pain first, and then the solution. Use "Bad example" and "Good example" with crosses and ticks, respectively, in captions.

    This structure can be used with images, videos, pieces of code, or text in boxes. Just make sure to include the appropriate caption for each element.

    Giving the bad example first will raise users' expectation...

    Figure: Bad example - Kid not in his seat

    Then showing the solution by giving a good example as the result, will make them feel released.

    kid in airplane seat
    Figure: Good example - Kid in his seat

    Usually, further information on how to achive the good example is added after the examples. E.g. Add a heading "More information" with extra details.

    You may also use "OK" examples for things that are acceptable but can be done better.

  6. DRY - Do you avoid repeated elements in content?

    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.

    DRY, which stands for ‘don’t repeat yourself,’ is a principle of software development that aims at reducing the repetition of patterns and code duplication in favor of abstractions and avoiding redundancy.

    This is especially valid for words in lists, but also applies to different types of content. You should keep only the part that is unique in each list item.

    Following this rule:

    • Is important to help you increase productivity
    • Is important to help you save time
    • Is important to help you reduce stress

    Bad example – Repeating words... Not following DRY :(

    Following this rule is important to help you:

    • Increase productivity
    • Save time
    • Reduce stress

    Good example – No repeated words... using the DRY principle

    Emojis

    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.

    ✅ Pros

    • ✅ Increases productivity
    • ✅ Saves time
    • ✅ Reduces stress

    ❌ Cons

    • ❌ May be challenging to implement
    • ❌ May take time to adjust
    • ❌ Can be challenging to maintain

    Bad example – Using an excessive amount of emojis. Not following DRY :(

    ✅ Pros

    • Increases productivity
    • Saves time
    • Reduces stress

    ❌ Cons

    • Requires effort to implement
    • May take time to adjust
    • Can be challenging to maintain

    Good example – Using the DRY principle

    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.

    Following the DRY principle by avoiding excessive repetition of words/emojis helps to create content that are visually interesting and easy to read, while also promoting efficient and maintainable content creation.

  7. Do you know the best screenshot tools?

    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

    Snagit - Recommended

    ShareX

    GoFullPage (Chrome Extension)

    Greenshot

    Lightshot

    Fullshot

    Flameshot

    Shottr (MacOS only)

    Preview (MacOS only - built-in)

    Snipping Tool (Windows only - built-in)

    screen shot 2022 06 09 at 16 38 10
    Figure: Lightshot is the most popular screenshot tool
    Source: Google Trends

    applicationframehost oa4wfguiqt
    Figure: Bad example - The Windows Snipping Tool isn't powerful enough for most business use cases

    screen shot 2022 07 28 at 11 18 57
    Figure: Good example - Snagit is the gold standard and provides tonnes of user friendly features

  8. Do you hide sensitive information?

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

    blurred image1
    Figure: Good example – Others can’t see the clients’ names

  9. Do you know to put borders around white images?

    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.

    white no border
    Figure: Bad Example - Can't tell where the image begins and ends!

    white border
    Figure: Good Example - This looks much better

    Note: You should also add a useful caption to every image.

  10. Do you distinguish keywords from surrounding content?

    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:

    "We found that moving CodeAuditor's scan engine (docker image) to be hosted on GitHub Action is not feasible."

    Figure: Bad example - it's possible to miss the word 'not'

    "We found that moving CodeAuditor's scan engine (docker image) to be hosted on GitHub Action is not feasible."

    Figure: Good example - The bolding draws attention to the main idea, which is 'No'!

    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

    Warning: Never underline the text if it isn't a link, as per Do you use underlines only on links?

    Use the following rules to highlight items in your document:

    StyleUse this style onExample
    Bold textMenus, commands, dialog box options, file names and pathsTo access the application, click Start | Programs | Accessories | System Tools | Disk Defragmenter
    Initial Capitals + BoldFile paths and file namesNow open C:\My Documents\Invoice.doc.
    Different colour stylingWeb UI - Important words on headingsWant to build an Angular application?
    UPPER CASECode keywords and database elementsUse the INNER JOIN clause in SQL Server to join one table to another.
    Monospace (Courier New font)Code samples, error messagesYou will see the following error: error opening database: database is currently in use.
  11. Do you use the right character for replaceable text placeholders?

    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:

    Figure: Bad example - Using square brackets for replaceable text

    Figure: Good example - Using double curly brackets for replaceable text... with spaces, and words in UPPERCASE

  12. Do you make quotes identifiable?

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

    Software development can be painful and costly. Hang on, that should say "Software development is painful and costly."

    Figure: Bad example - The quotation without a new line (or indent)

    Software development can be painful and costly. Hang on, that should say:
      "Software development is painful and costly."

    Figure: Good example - The quotation on a new line and indenting

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

    bad example adding quotations
    Figure: Bad example - It is hard to tell where the quote is

    good example adding quotations
    Figure: Good example - It is obvious that this is a quote and it is laid out nicely

  13. Numbers - Do you use numbers digits instead of words?

    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:

    There are seventy three good reasons to do this.

    Figure: Bad example - The number is spelled out

    There are 73 good reasons to do this.

    Figure: Good example - This is easier to read and more noticeable

    Certain editorial guidelines suggest using numerals for numbers 10 and above, while numbers 9 and below should be written out. However, when it comes to web content, we generally prefer using numerals regardless.

  14. Numbers - Do you use separators to improve numbers' readability?

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

    • Total: $27216
    • Phone: 14XXXXXXXXX

    Figure: Bad example - These numbers are unwieldy and difficult to read

    • Total: $2,721.65
    • Phone: +1 XXX XXX XXXX

    Figure: Good example - Symbols or some spaces make these large numbers easier to read

    Note:

    For currency references, different countries use periods in place of commas and vice-versa.
    E.g. In the United States and Australia: $2,367.48 / In France and Brazil: $2.367,48.

  15. Do you know how to format addresses?

    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

    Level 1, 81-91 Military Rd | Neutral Bay - NSW, 2089 Australia

    Figure: Bad example - SSW main office address not following the standard address formatting

    Level 1/81-91 Military Rd, Neutral Bay, NSW 2089, Australia

    Figure: Good example - SSW main office address following the standard address formatting

  16. SEO - Do you use descriptive links?

    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.

    "For tips and tricks to increase your Google Ranking click here"

    Figure: Bad example #1 - Generic words on links won't help your website rankings

    "Link for tips and tricks to increase your Google Ranking"

    Figure: Bad example #2 - Generic words on links won't help your website rankings

    "For tips and tricks to increase your Google Ranking read this"

    Figure: Bad example #3 - Generic words on links won't help your website 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.

    "For tips and tricks to increase your Google Ranking go to https://www.ssw.com.au/rules/rules-to-better-google-rankings"

    Figure: Bad example #4 - Whole URL on links won't help your users

    "For tips and tricks to increase your Google Rankings go to Rules to Better Google Rankings"

    Figure: Good example - Descriptive links will help your website rankings and the users

  17. Do you know to keep your URLs clean?

    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.

    Note: URLs have become increasingly cluttered with the introduction of CampaignIDs (used to track customer activities and other information). When you're sharing the URLs, it is better to make them as clean and readable as possible... So, delete everything after the question mark (including the CampaignID suffix).

    Figure: Bad example - Dirty URL with superfluous information

    Figure: Good example – Clean URL on a new line is easy to read and looks much better

    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.

    ppt urls bad
    Figure: Bad example - Showing unnecessary extra noise: "https://www."

    ppt urls good
    Figure: Good example - Clean links in a presentation

  18. Do you know how to capitalize titles and headings?

    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

    "The Lord of the rings – Return of the king"

    Figure: Bad example for titles - Inconsistency on words' capitalization

    "The Lord of the Rings – Return of the King"

    Figure: Good example for titles - Only conjunctions and prepositions (both having similar rules) should not be capitalized. E.g. "at", "on", "but", "and", "with", etc

    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.

    rules to better technical documentation example
    Figure: Good example - The main title has capitalization and the subtitles don't

  19. Do you know to capitalize tech terms correctly?

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

    john bristow tweet
    Figure: John Bristowe tackled some of the most commonly confused tech names in this tweet

    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") |

    bad example incorrect capitalization
    Figure: Bad example - If you want to be taken seriously as an expert in the subject, you should properly and consistently spell, punctuate, and capitalize the technology you are working with

    good example correctly capitalized
    Figure: Good example – the technology is consistently capitalized correctly across the page

  20. Do you know "Scrum" (and other Scrum terms) should be capitalized?

    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

    SSW CodeAuditor enforces this rule https://codeauditor.com/rules

    TODO: When the CodeAuditor box (on the Rules website is ready), update the greybox above. https://github.com/SSWConsulting/SSW.Rules/issues/417

  21. Do you know to always be careful with your spelling, grammar, and punctuation?

    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.

    grammarly plugin
    Figure: A typo caught by Grammarly plugin

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

    grammarly
    Figure: A typo caught by Grammarly

    Documents

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

    Microsoft Word has a spelling and grammar checker
    Figure: Click on "Spelling & Grammar" button to check your web content

    Presentations

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

    ppt review f7
    Figure: Click on "Spelling" button to check your web content

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

    ppt check spelling
    Figure: Make sure "Check grammar with spelling" is enabled

  22. Do you avoid common spelling and syntax mistakes?

    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")

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

  23. Do you avoid acronyms in your writing?

    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.

    Ash: I'm attending FBC next week.

    Eddie: What is FBC?

    Bad example: This conversation is unclear as Eddie doesn't know FBC

    Ash: I'm attending FireBootCamp next week

    Eddie: Awesome!

    Good example: No acronyms so it is a clear conversation

    Ash: I'm attending FireBootCamp (FBC) next week. Would you like to start the SugarLearning (SL) this week?

    Eddie: Great! I'll start SL this week.

    Good example: Defined acronyms

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

    NB: Track this.

    Bad example: NB is unclear and old-fashioned

    Note: Track this.

    Good example: "Note" is more common and understandable

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

  24. Do you use "will", not "should" for processes?

    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!).

    To print your document:

    1. Select File | Print. The Print dialog should now show
    2. Select the number of copies and click "Print". The file should now print

    Figure: Bad example - Using "should" implies uncertainty

    To print your document:

    1. Select File | Print. The Print dialog is shown
    2. Select the number of copies and click "Print". The file will now print

    Good example - Using present or future tense implies confidence

    This is not detected by SSW CodeAuditor because it picks up false positives.

  25. Do you use right terms for user authentication?

    The words we choose can significantly impact user experience. One such area of careful consideration is the language surrounding user authentication.

    User authentication

    While "Log in" has been widely used in the past, for modern applications it is preferred to use "Sign in". The term is widely recognized, intuitive, and aligns well with the modern user's expectations.

    Note: The term "Login" as a noun (no spaces) is still widely used in content, often interchangeably with the term "username."

    Warning: It's advised to steer clear of using "logon." This term, although it may have historical roots, has fallen out of favor and could potentially confuse users. Opting for more widely accepted alternatives ensures a smoother user experience.

    Use "Register" for creating acccounts

    When prompting users to create accounts, "Sign up" may cause confusion with "Sign in". Based on that, "Register" can offer a clearer indication of the action being taken, fostering a sense of formality and commitment.

    Note: "Join" is a versatile term that can be suitable, depending on the context. For instance, it works well when inviting users to become part of a group or community.

    Always align terminology with the expectations and preferences of your target audience to create a seamless and positive interaction. By embracing the clearer, user-friendly terms "Sign in" and "Register" we can contribute to a more intuitive and consistent user experience.

  26. Do you use "Try Again" instead of "Retry"?

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

    Figure: Good example - Internet Explorer uses "Try Again" instead of "Retry"

  27. Do you know commas and full stops always should have 1 space after them?

    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:

    Looking for your sent emails through a searching tool is simple.By using Windows Desktop search,you can search your relevant emails by recipient and/or by subject.

    Figure: Bad example - No space after comma and full stop

    Looking for your sent emails through a searching tool is simple.  By using Windows Desktop search,  you can search your relevant emails by recipient and/or by subject.  

    Figure: Bad example - Two spaces after comma and full stop

    Looking for your sent emails through a searching tool is simple. By using Windows Desktop search, you can search your relevant emails by recipient and/or by subject.

    Figure: Good example - One space after full stop and comma

  28. Do you know to use lowercase after "-"?

    Use lowercase after "-" in a text.

    “Make a change to the content of the system you're currently looking at - If you don't know it is called SugarLearning, then we have a real problem :)”

    Figure: Bad example - Uppercase after "-"

    “Make a change to the content of the system you're currently looking at - if you don't know it is called SugarLearning, then we have a real problem :)”

    Figure: Bad example - lowercase after "-"

  29. Do you refer to the reader and author consistently throughout your document?

    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.

    When one wants to scan for viruses, you can open the antivirus software.

    Figure: Bad example - The user is referred in two ways and flow is broken

    When you want to scan for viruses, open the antivirus software.

    Figure: Good example - There is no noticeable break in the reading flow

    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.

    We will now open a web browser and go to the home page.

    Figure: Bad example - It is unclear who the "we" is

    You can now open a web browser and go to the home page.

    Figure: Good example - These instructions are clear and direct

  30. Reference - Do you use the correct symbols when documenting instructions?

    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:

    ...then you click on All Apps from the Start menu

    Figure: Bad example - Wrong order and too many words

    Click Start, then All Apps, then Accessories, then Calculator.

    Figure: Bad example - No visual cue is given for separate steps

    Start - All Apps - Accessories - Calculator

    Figure: Bad example - Dashes are easy to glance over

    Start --> All Apps --> Accessories --> Calculator

    Figure: Bad example - This is better but may be interpreted incorrectly

    Start | All Apps | Accessories | Calculator

    Figure: Good example - Makes it easy to follow

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

  31. Do you use emojis to help give context?

    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 + .)!

    Teams Emojis Bad
    Figure: Bad example - Teams Channel names without emojis

    Teams Emojis Good
    Figure: Good example - Teams Channel names have emojis

    control4 emojis
    Figure: Good example - Control4 automation Mobile UI is more friendly with emojis

    calendar emoji
    Figure: Good example - Some appointments can benefit from an emoji too, like a Sprint meeting in Scrum

    • Fast to load (lightweight as no image)
    • UI - Consistent look
    • Maintenance of needing to upload to server

    Bad example - Regular list items

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

    ✅ Fast to load (lightweight as no image)
    ✅ UI - Consistent look
    ❌ Maintenance of needing to upload to server

    Good example - Emojis give context to each item

  32. Do you know where to add new lines?

    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.

    Good way: use the Dynamics 365 (formerly CRM 2016) toolbar? Note: We have a suggestion that Outlook should allow you to put the CRM2016 URL into Tools | Options so this is better integrated

    Figure: Bad Example - No line break before the note.

    Good way: use the Dynamics 365 (formerly CRM 2016) toolbar?
    Note: We have a suggestion that Outlook should allow you to put the CRM2016 URL into Tools | Options so this is better integrated

    Figure: Good Example - The note being on a fresh line makes it much easier to read.

    This is also recommended when sending URLs for readability.

    Hey Bob,

    Check out this awesome new video about the SSW Cultural Exchange Program! https://youtu.be/dfE_Y8fy_wo?si=NEcQLAPafAWKa7m5

    Figure: Bad Example - No line break before the URL.

    Hey Bob,

    Check out this awesome new video about the SSW Cultural Exchange Program!

    https://youtu.be/dfE_Y8fy_wo?si=NEcQLAPafAWKa7m5

    Figure: Good Example - The URL being on a fresh line makes it much easier to read.

    This is also recommended when sending PBIs for better readability.

    Hey Adam,

    I have 2 PBIs on my next to-do in the coming sprint: Product Backlog Item 88994: ⚡Performance | Create a new App Service plan and Product Backlog Item 88823: 🚗 Azure | Create a new App Service Plan in West US for SL production resource group. I will do the IoC after.

    Figure: Bad Example - No new lines for PBIs.

    Hey Adam,

    I have 2 PBIs in this Sprint:

    • PBI 88994: ⚡Performance | Create a new App Service plan
    • PBI 88823: 🚗 Azure | Create a new App Service Plan in West US for SL production resource group. I will do the IoC after.

    Figure: Good Example - PBIs on a new line.

    This rule is enforced by CodeAuditor. https://codeauditor.com/rules

    See the Markdown Guide for more information on line breaks.

  33. Reference - Do you use quotation mark for controls?

    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.

    Click the Upgrade link

    Figure: Bad Example - It's not clear that Upgrade is a control

    Click the "Upgrade" link

    Figure: Good Example - This is much clearer to the user what to search for

  34. Sample Names - Do you use generic and consistent names on examples?

    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.

    Hi Mark Zuckerberg,

    We need to make sure the project Facebook app will be approved before summer.

    Regards,

    Bad example - Using real people and real companies as examples

    Hi Bob,

    We need to make sure the project Northwind app will be approved before summer.

    Regards,

    Good example - Using dummy consistent names on examples

  35. Do you make URLs short and readable?

    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.

    Link: blog2.northwind.com/archive/2022/10/25/now-available-visual-studio-2022-rtm-virtual-machine-with-sample-data-and-hands-on-labs.aspx

    Bad example - The long URL makes it hard to clearly see what it will take you. People can’t easily type or remember it

    Link: northwind.com/blog/visual-studio-2022-sample-data

    Good example - The nice and clean URL makes it easy to see what the link is about

    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.

    northwind.com/how-do-i-find-the-version-of-the-word-document.html

    Figure: Bad example - The filler words remain

    northwind.com/find-word-document-version

    Figure: Good example - The filler words removed and only 'juicy' words remain

    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.

    Auto-shorten link: bit.ly/3zTHz8b

    OK example - Auto-generated shorten URL - It's short but hard to remember

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

    Custom shorten link: bit.ly/VS-2022-Sample

    Good example - Short URL, and easier to remember

  36. Do you know how to name documents/files?

    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

    Monthly Report.docx

    Figure: Bad example - File name using spaces to separate words

    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

    MonthlyReport.docx

    Figure: Bad example - File name using CamelCase doesn't have spaces but also doesn't contain any separators between words

    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

    Monthly_Report.docx

    Figure: OK example - Underscored (Snake_Case) URLs have good readability but are not recommended by Google

    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

    monthly-report.docx

    Figure: Good Example - File name uses kebab-case (dashes to separate words)

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

    You may use Uppercase in the first letter in Kebab-Case, however it's important to keep consistency

    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.

  37. Do you have version numbers in documents and design files?

    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.

    scrum image version number
    Figure: Good example - Version number on the RHS of a design document

    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

    Add major version numbers in internal file names

    For internal use, 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. For public files you should not include version numbers.

    Warning: This should only be changed on major versions and only on internal documents.

    codeauditor\file.pdf codeauditor\new\file.pdf codeauditor\file_latest.pdf

    Figure: Bad example - Internal file names do not show any version information

    codeauditor\filev1.pdf codeauditor\filev2.pdf codeauditor\file_v3.pdf

    Figure: Good example - Internal file names show the version information

  38. Do you remove spaces from folders and files names?

    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.

    • extremeemailsversion1.2.doc
    • Extreme Emails version 1.2.doc

    Figure: Bad examples - File names have spaces or dots

    • extreme-emails-v1-2.doc
    • Extreme-Emails-v1-2.doc

    Figure: Good examples - File names have dashes instead of spaces

    • sharepoint.ssw.com.au/Training/UTSNET/Pages/UTS%20NET%20Short%20Course.aspx
    • fileserver/Shared%20Documents/Ignite%20Brisbane%20Talk.docx

    Figure: Bad examples - File names have been published to the web with spaces so the URLs look ugly and are hard to read

    • sharepoint.ssw.com.au/Training/UTS-NET/Pages/UTS-NET-Short-Course.aspx
    • fileserver/Shared-Documents/Ignite-Brisbane-Talk.docx"

    Figure: Good examples - File names have no spaces so are much easier to read

  39. Do you document/update processes before sending "Done"?

    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
  40. Do you produce the best End-User Documentation?

    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

    Content - Easy to edit

    Navigation - Has nice navigation on the left

    Copying Code - No code elements for technical training

    No Google Analytics

    Not native to the web

    Option 2: Plain HTML pages

    You have complete control over how it looks

    Can add Google Analytics

    Content - Hard to edit using HTML

    Navigation - Does not have any navigation

    Copying Code - No code elements for technical training

    Lacks basic features, like search

    Option 3: GitBook.com (recommended)

    Content - It's in Markdown

    Navigation - Has nice navigation on the left

    Copying Code - If you have code elements for technical training it allows easy copying and pasting Simple Branding options

    $ - The base version is free for everyone else

    $ - The full version is free for open-source communities.

    It allows you to change the subdomain (only in full version)

    It's in GitHub - allows people to give suggestions

    Integrated search

    Integrated with Google Analytics

    gitbook

  41. Do you use Architectural Decision Records (ADRs)?

    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

    ADR Examples

    adr
    Figure: Example ADR from SSW.CleanArchitecture

    You can see more examples of ADRs with log4brains in action on our SSW.CleanArchitecture template.

  42. Prefixes - Do you know why they are awesome?

    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

    badexamplenocontext
    Bad example - There is no context provided in the title, it could be about subjects for Meetings, Conferences, Videos or something entirely different

    okayexamplehascontext
    OK example - The context is included in the title

    goodexamplehascontextviaprefix
    Good example - The prefix very clearly identifies the subject in the title

  43. Do you know all the symbols on the keyboard?

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

  44. Do you know how to copy text from an image?

    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.

    one note 1
    Figure: Paste image into OneNote and right click on it

    one note 2
    Figure: Good example - The text pastes below the image. Easy!

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

    drive 1
    Figure: Upload your image first

    drive 2
    Figure: Open your image with Google Docs

    drive 3
    Figure: Good example - The text is added to the new document!

We open source. Powered by GitHub