Secret ingredients to quality software

SSW Foursquare

Rules to Better Technical Documentation - 46 Rules

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

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

    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. General web content should always be written as if read by a newsreader. It is objective and describes its content professionally. A good example of this is Wikipedia.

    I don't like JavaScript. I prefer jQuery because...

    Figure: Bad Example - using 1st person writing makes it sound like opinion

    jQuery is superior to JavaScript for this because...

    Figure: Good Example - using 3rd person writing makes it sound like fact

    When quoting a testimonial, you should use 1st person writing as if a newsreader had crossed over to an eyewitness for a personal view of the topic.

    Don Bradman thought that SSW's work was fantastic!

    Figure: Bad Example - impersonal

    Don Bradman says: "I thought that SSW's work was fantastic!"

    Figure: Good Example - 1st person in this context is appropriate

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

  5. It is important to use correct capitalization when writing titles/headings for things.

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

    Figure: Bad Example – The first letter of the first and last words should always be capitalized

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

    Figure: Good Example – 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 (which are important), and leave subtitles in normal sentence form. Basically it saves hassles... English is a confusing language and there are too many variations that cause too many arguments.

    good example of capitalizing titles
    Good Example - the main title has capitalization and the sub-titles don't

  6. 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:

    StyleUse this style onExample
    Bold textMenus, commands, dialog box options, file names and pathsTo access the application, click **Start
    UPPER CASECode keywords and database elementsUse the INNER JOIN clause in SQL Server to join one table to another.
    Initial Capitals + BoldFile paths and file namesNow open C:\My Documents\Invoice.doc.
    Monospace (Courier New font)Code samples, error messagesYou will see the following error: error opening database: database is currently in use.

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

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

  8. Do you include version numbers in your file?

    It is very important to have your Word, PowerPoint, PDFs and other documents up-to-date and having the version number on the RHS of the footer is the best way to show which version you are looking at.

    Please read to understand 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

    It is also good practice to include a version number in the name of the file. This helps us to navigate through the old and the new versions. It makes it easy if we decide to roll back any changes and use an older version.

    For example:

    extreme_email_file extreme_email_new_file extreme_email_latest

    Figure: Bad Example - These files do not show any version information.

    Extreme_Emails_v1 Extreme_Emails_v2 CodeAuditor_Ver1 CodeAuditor_Ver2

    Figure: Good Example - These files show the version information.

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

  10. Do you avoid using unnecessary words?

    When writing any documentation it is vital that you avoid using unnecessary words to keep the reader interested and focussed on the content. This is especially true in technical documentation, as most of the content is factual.

    Click the "Select" button

    Figure: Bad Example - There are too many unnecessary words

    Click "Select"

    Good Example - This is short and to the point.

    It is less wordy, and still gets the message across. Look through your document now - where else can you get rid of words that don't add any value to the sentence?

  11. Numbers - Do you make numbers more readable?

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

    • $27216
    • Phone: 8583532311

    Bad Example: These number are unwieldy and difficult to read

    • $2,721.65
    • Phone: (858) 353-2311

    Good example: A comma, a dash and some spacing makes these large digits easier to read

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

  12. Do you know how to format addresses?

    Use a consistent format when writting 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

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

    For example:

    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

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

    Documents

    When 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

    Presentation

    When 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

    Web Content

    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

  15. Numbers - Do you use digits instead of words?

    Whenever writing numbers for a web audience, 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 easy to read and more noticeable

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

  17. An important area which Microsoft does not apply strict standards to, is documenting instructions. This is often a confusing dilemma for many people, as 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.

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

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

    Start - All Programs - Accessories - Calculator

    Figure: Bad Example - Dashes are easy to glance over

    Start --> All Programs --> Accessories --> Calculator

    Figure: Bad Example - This is better but looks unprofessional

    Start | All Programs | Accessories | Calculator

    Figure: Good Example - Makes it easy to follow

    We often see documentation like: 'Select All Programs from the Start menu'. This is bad! you must always list the items in the order the user selects them.

  18. When writing the instructions for a series of operations, be sure you keep the operations in the right order. With a clear order, users will be less likely to be confused.

    At SSW, convention is to use the pipe character "|" to indicate a step in a navigation process.

    Select Options from the Tools Menu.

    Figure: Bad Example - These instructions are in reverse and needs to be processed by the user.

    Select Tools | Options

    Figure: Good Example - These instructions are in order and do not require any effort from the user.

  19. Some people communicate with a 'Wall of Text'. Communicate better by using screenshots and reduce your amount of words.

    You can take screen captures to the next level by adding balloons that have the appropriate text (aka speech bubbles). Sometimes you need only the text in the balloon and no text in the email.

    The balloon is great because you can point to a specific part of the image. It is much easier than reading the old ‘Wall of Text’.

    Going further, there are ways to improve readability of your screenshots:

    Tip 1: Add a balloon when you need to point at an specific area of your screenshot

    BalloonBadExample
    Figure: Bad Example – The email is using a screenshot so that is good, but you need to read the text and relate it to the image

    BalloonGoodExample
    Figure: Good Example – The balloon with text on the screenshot, makes it quicker to understand

    Tip 2: Be aware not to overuse balloons!

    balloon overload
    Figure: Bad Example – Balloon overload

    Figure: Good Example – See 3 balloons were not needed

    arrow example
    Figure: Good Example - Sometimes an arrow is all that is needed

    In other words, you can use:

    • Plain screenshots
    • Balloons
    • Circles or boxes
    • Arrows

    They are all useful depending on the scenario. Be wise and try to make it as clear as possible to the reader.

    Tip 3: Add branding to screenshots

    Follow the rule Do you add branding to screenshots?

    Figure: Betsy Weber Techsmith - Part 1 - Creator of Snagit. See full series here

  20. Do you add branding to screenshots?

    It is great when people use screenshots. You can communicate better by using screenshots with balloons and other visual elements (arrows, shapes, and highlights) instead of only text. Read the benefits of using screenshots.

    We recommend you define a standard style for your visual elements by changing the default colors and shapes according to your branding.

    See some examples of different visual elements under same branding:

    screenshot1
    Figure: Indicate someone to enter the mobile field. Do you use a red arrow?

    screenshot2
    Figure: Or do you like the red box?

    screenshot3
    Figure: Or do you like the yellow highlight?

    More Information on SSW Branding

    You can automatically have the SSW Snagit presets on sign-in via a script.

    Instructions to create and use Snagit themes can be found at Quick Style Themes Tutorial.

  21. Often when writing technical documents, you will instruct the reader to 'set up' his PC or run a 'setup' file. Remember that 'set up' is a verb, and 'setup' is a noun.

    Verify that your network setup is correct before attempting to connect to the Internet.

    Figure: Good Example - This is the correct use of "setup"

    Click Go to set up your database.

    Figure: Good Example - This is the correct use of "set up"

    'Set up' is a verb with many meanings, most commonly 'to establish something.' 'He is going to set up shop.'

    The single word 'setup' is a noun, basically meaning an 'arrangement.' 'The setup was all wrong.'

    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 shop' makes sense. 'The setting up was all wrong' does not.

  22. Tiny: Do you use "will", not "should"?

    When explaining steps in a process, e.g. 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, i.e. 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 Code Auditorbecause it picks up false positives.

  23. 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"

    Would you like to logon to your new account? Would you like to log-on to your new account? Would you like to login to your new account? Would you like to log-in to your new account? Would you like to signin to your new account? Would you like to sign-in to your new account?

    Figure: Bad examples

    Would you like to log in to your timesheeting application?

    Figure: Good example - Winform

    Would you like to sign in to your email account?

    Figure: Good example - Webform

    Would you like to log on to your computer?

    Figure: Good example - PC, Server or Domain

    See the Login From Wikipedia.

    We have a program called SSW Code Auditor to check for this rule.

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

    Figure: Internet Explorer uses "Try Again" instead of "Retry

  25. This is a common item that trips people up: taskbar is one word, not two.

    Taskbar is one word, not two

    Figure: Good Example - You should use the "taskbar" over "task bar"

  26. Grammatically, all of them are acceptable spellings, but in these specific cases, one word is more usual. Refer to AskOxfordfor reference.

    Note: When there are two ways of doing something, we make a rule on it one way with the goal of having complete consistency.

    You can not change the world.

    Figure: Bad example – two separated words

    You cannot change the world.

    Figure: Good example - using these terms in one word

    We have a program called SSW Code Auditor to check for this rule.

  27. Microsoft Word spell checker is lenient about 'email' versus 'e-mail', but you should use 'email' instead.

    What if you wanted to say "Re-email this report please"... surely you would not say "Re-e-mail this report."

    We have a program called SSW Code Auditor to check for this rule.

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

  29. 'That' is occasionally an unnecessary addition to a sentence, especially if it's a title that would benefit from being short and punchy. As such, avoid using "that" in a title wherever possible.

    "Building Software that People Understand"

    Figure: Bad Example - unnecessary "that"

    "Building Software People Understand"

    Figure: Good Example - without the "that", the setence is concise and has more punch

  30. Excess punctuation without a purpose can make a document or web page look overly busy.

    For lists of short sentences and figure captions, don't add full stops at the end. Of course when you have more than one sentence, add the full stops where necessary, then only avoid the full stop in the last sentence.

    • Sentence 1.
    • Sentence 2.
    • Sentence 3.

    Figure: Bad Example - Too much punctuation

    • Sentence 1
    • Sentence 2. Sentence 3
    • Sentence 4

    Figure: Good Example - Full stop is only used when necessary - multiple sentences

  31. Words like “verses” and “versus” are homophones, meaning they are pronounced the same, but have different spellings and different meanings.

    When using a homophone in a sentence, it is important to ensure you are using the correct word, as if you are not, it won’t be picked up by your spell check and you'll look less intelligent.

    In this case, “verses” refers to lines of poetry or bible passages. “Versus” refers to 2 or more parties in opposition to one another, especially in sports or legal situations.

    “Versus” can be shortened to “vs.”, which is common insporting situations, or “v.”, which is the standard abbreviation for legalscenarios.  

    "Matthew 5:41 is one of my favourite bible versus."

    Figure: Bad example: the wrong “versus” is used

    "Floyd verses Mayweather."

    Figure: Bad example: Floyd did not poetry Mayweather

    "Brown v. The Board of Education."

    Figure: Good example: in a legal context, “versus” is abbreviated to “v.”

    "Adam penned many verses about his love for .NET development"

    Figure: Good example

  32. Tiny: Do you use "Note" instead of "NB"?

    In a piece of writing, both “NB” and “Note” can be used to add a piece of information or attract the reader’s attention to an important detail. Of these 2 options, it is better to use “Note” than to use “NB”. 

    This is because NB is old-fashioned – it is the abbreviation for “nota bene”, Latin for “note well” – and its meaning is not immediately clear, whereas the meaning of “note” is immediately obvious. It is always better to use plain English, and to avoid abbreviations that could be confused for something else. Therefore, you should use “note” in your documentation to ensure your meaning is clear.

    NB: It is important to track the length of this process.

    Bad example: NB is unclear and old-fashioned

    Note: It is important to track the length of this process.

     Good example: It is obvious what we mean when we use "Note"

  33. To get the most out of your communications, your writing should be compelling and direct. The best way to ensure this is to use active voice.

    For example:

    When the CD is inserted, a Windows dialog will be shown.

    Figure: Bad Example - This example is using a passive voice, and does not address the reader or from the point of the subject (the software in this case).

    When you insert a CD, Windows shows a dialog.

    Figure: Good Example - This example uses the active voice to address the reader, and is more direct and engaging.

    An easy way to tell if you're using the passive voice is to add "by zombies" after verb. If your sentence still make sense, you're using passive voice. 

    The email was sent by zombies

    Figure: Bad example - This sentence could be more engaging

    Zombies sent the email 

    Figure: Good example - Now that's a more engaging sentence

    3 reasons you should avoid passive voice:

    1. Passive voice uses more words - in the figures above, the "Bad Example" uses 6 words whereas the "Good example" uses only 4
    2. It's less logical - instead of having the subject do something to the object, the object does something to the subject
    3. It's less clear - In the bad example above, you don't know who was acting until the end of the sentence, whereas in the good example, you know immediately.
  34. Do you add a prefix on blog posts titles?

    The prefix is used to give context to your blog posts (or other type of content), so users know what to expect.

    Example 1: Use " CODE:" when your blog post is about coding  or " VIDEO:" when it has a video.

    Northwind Traders with Entity Framework Core

    Figure: Bad example - Post title with no prefix

    CODE: Northwind Traders with Entity Framework Core

    Figure: Good example - Using a prefix in the post title

    Example 2: Use prefixes (based on the content) for grouping and a better scanning:

    Configure your SSW Email on your mobile (for Android users) Configure your SSW Email on your mobile (for iPhone users) Mobile Phone Answering Message Install the Control4 App on your phone (Sydney Only) Configure Skype for Business (Not for China office) Configure Skype Link your Azure & Azure DevOps (was VSTS) benefits to your SSW Organizational Account Request Access to VSTS Projects Do you know how to find stuff? Setup and Create a timesheet in TimePRO Setup your HR Records (Not for Work Experience) Your details on payroll system CRM - Add your details to CRM How to find an employee’s phone number? Make a small code change on SugarLearning.com (Developers only)

    Figure: Bad example - Data list with no prefixes

    Phone - Configure your SSW Email on your mobile (for Android users)  Phone - Configure your SSW Email on your mobile (for iPhone users)  Phone - Mobile Phone Answering Message  Phone - Install the Control4 App on your phone (Sydney Only)  PC - Configure Skype for Business (Not for China office)  PC - Configure Skype  DevOps - Link your Azure & Azure DevOps (was VSTS) benefits to your SSW Organizational Account  DevOps - Request Access to VSTS Projects  Intranet - Do you know how to find stuff?  TimePro - Setup and Create a timesheet in TimePRO  CRM - Setup your HR Records (Not for Work Experience)  CRM - Your details on payroll system CRM - Add your details to CRM  CRM - How to find an employee’s phone number?  Exercise - Make a small code change on SugarLearning.com (Developers only)

    Figure: Good example - Using a prefix in data

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

  36. Do you avoid using gendered pronouns?

    Historically, it’s been the convention to refer to users as ‘he’ in technical documentation. This is obviously outdated and sexist – users may not be a "he". It’s more common now to see "he/she" used, but this is clunky and could also still be considered as misgendering non-binary people.

    The best pronoun to use is "they". It’s simple and elegant and doesn't exclude anyone.

    This feature is particularly important if the user runs a semi-long task (e.g.30 seconds) once a day. Only at the end of the long process can he know the particular amount of time, if the time taken dialog is shown after the finish. If the status bar contains the time taken and the progress bar contains the progress percentage, he can evaluate how long it will take according to the time taken and percentage. Then he can switch to another work or go get a cup of coffee.

    Bad example: User referred to as "he"

    This feature is particularly important if the user runs a semi-long task (e.g.30 seconds) once a day. Only at the end of the long process can they know the particular amount of time, if the time taken dialog is shown after the finish. If the status bar contains the time taken and the progress bar contains the progress percentage, they can evaluate how long it will take according to the time taken and percentage. Then they can switch to other work or go get a cup of coffee.

    Good example: User referred to as "they"

  37. 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 "-"

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

  39. It is a good idea to create a dummy company to represent all clients on internal documentation, including a made-up name for the person behind that company. At SSW, anytime we need an example of dealing with clients, we 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 and we don't want to expose our real clients names.

    Hi Mark Zuckerberg , We need to make sure our project with Facebook will be approved before summer.

    Regards

    Bad example - Using real people and real companies as examples

    Hi Bob, We need to make sure our project with Northwind  will be approved before summer.

    Regards

    Good example - Using dummy consistent names on examples

  40. Do you use relevant words on your links?

    We know that the way your inbound links are worded does make a difference, they play an important factor when Google searches are made by search engine users.

    Having these relevant words on links also gives a more friendly experience to the 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 the,.

    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 - Link does not increase your rankings

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

    Figure: Bad Example #2 - Link does not increase your rankings

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

    Figure: Bad Example #3 - Link does not increase your rankings

    "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 - Link is the whole URL

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

    Figure: Good Example - Descriptive link

  41. Do you spell 'email' correctly?

    There is one correct way to spell 'email' and many incorrect ones. The common incorrect ones are:

    • EMail
    • e-mail

    Lower Case with dash:

    <p>Your e-mail address must match your confirm e-mail address</p>

    Bad example: Using 'e-mail' in your text

    <p>Your email address must match your confirm email address</p>

    Good example: Using 'email' instead

    Upper Case with capital M:

    <input class="form-control" data-val="true" data-val-required="The EMail field is required." id="EMail" name="EMail" placeholder="EMail" type="email" value="" data-cip-id="EMail" autocomplete="off">

    Bad example : 'EMail' used as a placeholder and in the validation message

    <input class="form-control" data-val="true" data-val-required="The Email field is required." id="Email" name="Email" placeholder="Email" type="email" value="" data-cip-id="Email" autocomplete="off">

    Good example: Use 'Email' instead 

    We have a rule in SSW Code Auditor and SSW Link Auditor to check for this.

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

    You will occasionally see it in:

    • not capitalized (scrum) - this is incorrect
    • all caps (SCRUM) - this is 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

  43. Do you know to keep your URLs clean?

    Step 1 - Remember to remove the https from your URLs in your presentations. It keeps the pages cleaner and more readable.

    ppt urls bad
    Figure: Bad Example – These links are showing the "https://"

    ppt urls good
    Figure: Good Example – These links are clean

    Step 2 - Even when you’re sending emails, or pinging someone in Teams, your URLs should be as clean as possible. This ensures that they are easy to read, and it is more aesthetically pleasing.

    URLs have become increasingly cluttered with the introduction of tracking information.

    For example, companies use CampaignIDs on their website to track customer activities and information, but when you’re sharing the URLs, it is better to make them clean and readable. So, delete everything after the question mark (including the CampaignID suffix).

    Figure: Bad Example - Dirty URL with superfluous information

    Figure: Good Example – Clean URL that is easy to read and looks much better

  44. 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 benificial 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 rule is enforced by CodeAuditor. https://codeauditor.com/rules

    See the Markdown Guide for more information on line breaks.

  45. Do you know how to name documents?

    When naming documents, use kebab-case to separate words to make your files more easily discoverable.

    Avoid spaces

    Monthly Report.docx

    Bad example: File name uses a space 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

    Bad example: CamelCase - File name 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

    Good Example: kebab-case - File name uses 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.

    • Use descriptive file names and titles

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

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

We open source. Powered by GitHub