Rules to Better Technical Documentation
36 Rules
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
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.
Figure: John Bristowe tackled some of the most commonly confused tech names in this tweet The main 5 types used are:
- All uppercase – ALL UPPERCASE
- All lower case – all lowercase
- Pascal case - PascalCase
- Camel case – camelCase
- 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") |
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 
Figure: Good example – the technology is consistently capitalized correctly across the page 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 - the main title has capitalization and the sub-titles don't Do you highlight actions correctly in your document?
When highlighting items (file names, user commands etc.) be sure to:
- Distinguish the items from the rest of the surrounding text; and
- Be consistent.
Use the following rules to highlight items in your document.
Style Use this style on Example Bold text Menus, commands, dialog box options, file names and paths To access the application, click **Start UPPER CASE Code keywords and database elements Use the INNER JOIN clause in SQL Server to join one table to another. Initial Capitals + Bold File paths and file names Now open C:\My Documents\Invoice.doc. Monospace (Courier New font) Code samples, error messages You 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?
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.
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.
Figure: Bad example - It is hard to tell where the quote is 
Figure: Good example - It is obvious that this is a quote and it is laid out nicely 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?
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
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.
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.
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.
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.
Figure: Click on "Spelling" button to check your web content You should also keep "Check grammar with spelling" checked in your PowerPoint Options | Proofing :
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.
Figure: A typo caught by Grammarly Related rule
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
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.
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
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.
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.
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.
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.
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 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"
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.
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.
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
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
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
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
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"
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:
- Passive voice uses more words - in the figures above, the "Bad Example" uses 6 words whereas the "Good example" uses only 4
- It's less logical - instead of having the subject do something to the object, the object does something to the subject
- 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.
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
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 | | --- | --- |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"
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 "-"
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
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
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.
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:
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.
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
