Rules

Secret ingredients to quality software

Edit
Info

Rules to Better Technical Documentation

36 Rules

  1. Do you write in the newsreader and eyewitness style?

    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

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

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

    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

  4. Do you highlight actions correctly in your document?

    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 when it isn't a link as per the rule: Do you use underlines only on links?

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

  6. Do you know how to make quotations easier to identify?

    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

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

  8. Do you make numbers more readable?

    Remember to use dividers when quoting 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

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

    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, you can 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.

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

    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

    Related rule

  11. Do you use words instead of digits for low numbers?

    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

    The exception is generally very small numbers (one and two) which are normally spelled out.

    2 heads are better than 1.

    Figure: Bad Example - Numerals used

    Two heads are better than one

    Figure: Good Example - Numbers are spelled out

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

  13. Reference: Do you use the correct symbols when documenting instructions?

    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.

    In Ken Getz's words, you MUST ALWAYS list the items in the order the user selects them. I often see on Microsoft documentation: 'Select All Programs from the Start menu'. That's inexcusable!

    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

  14. Reference: Do you use the right order of instructions?

    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.

    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.

  15. Tiny: Do you use "setup" and "set up" correctly?

    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.

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

  17. Tiny: Do you know when to use "log on", "log in", and "sign in"?

    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.

  18. Tiny: 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: Internet Explorer uses "Try Again" instead of "Retry

  19. Tiny: Do you use "Taskbar" instead of "Task Bar"?

    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"

  20. Tiny: Do you use "cannot" and "website" instead of separated words?

    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.

  21. Tiny: Do you know "email" does not have a hyphen?

    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.

  22. Tiny: 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

  23. Tiny: Do you avoid using "that" when it's not needed?

    '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

  24. Tiny: Do you avoid full stops at the end of bullet point lists?

    Excess punctuation without a purpose can make a document or web page look overly busy. For a list of short sentences and for  figure captions , don't add full stops at the end. The exception to this rule is when you have more than one sentence, then only avoid the full stop in the last sentence .

    For example:

    • 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 in the bullet point that has multiple sentences, except in the last one

  25. Tiny: Do you know when to use versus and verses?

    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

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

  27. Tiny: Do you use active phrases? (No zombies please)

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

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

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

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

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

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

  34. 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. Google uses the words between your <a href> tags to decide which websites are the most relevant to the search terms.

    **Having these relevant words on links also gives a more friendly experience to the users. **

    For example, if SSW had a million inbound links that described the site like this...

    <a href="http://www.ssw.com.au">Movies for Free</a>

    ...when someone searches for "free movies" on Google, it would point to us.
    So what does this mean? All those that are pointing to pages on your website that are 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

    "Linkfor 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 Click Here"

    Figure: Bad Example #4 - Link title does not increase your rankings (scroll and hold over link to see it)

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

    Figure: Bad Example #5 - 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

    This rule also has relevance for easier website navigation.

  35. Spelling - Do you write the word 'email' in the correct format?

    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.

  36. Grammar - Do you know "Scrum" should be capitalized?

    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

We open source. This page is on GitHub