Rules to Better Technical Documentation - 46 Rules
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?"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.
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
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 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 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 if it isn't a link, as per Do you use underlines only on links?
You should always use discretion in your public documentation. Hide any sensitive information, like your clients’ names, from screenshots and general documentation.
Figure: Good example – Others can’t see the clients’ names 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.
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 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?
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.
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
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
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
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
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
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.
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.
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
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 
Figure: Good Example – The balloon with text on the screenshot, makes it quicker to understand See more details on how to configure balloons branding in Fullshot and Snagit.
Tip 2: Be aware not to overuse balloons!
Figure: Bad Example – Balloon overload 
Figure: Good Example – See 3 balloons were not needed 
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 hereIt 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:
Figure: Indicate someone to enter the mobile field. Do you use a red arrow? 
Figure: Or do you like the red box? 
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.
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.
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.
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.
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 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"
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.
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.
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
'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
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
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
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"
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.
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
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 | | --- | --- |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"
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 "-"
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
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
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
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.
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
Step 1 - Remember to remove the https from your URLs in your presentations. It keeps the pages cleaner and more readable.
Figure: Bad Example – These links are showing the "https://" 
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).
To: Adam Cc: YYY Bcc: ZZZ Subject: Purchase please - new hand dryer Hi Adam,
Here is the link to the new hand dryer that you wanted to see:
Vortex Hand Dryer, Super Quiet motor, 3 Years Warranty OZ2100 $184 (no electrical installation required – plugs in – for the men's bathroom upstairs) https://www.ozwashroom.com.au/hand-dryer-285?campaignid=1683143023&adgroupid=62945164502&keyword=&device=c&gclid=Cj0KCQjw--GFBhDeARIsACH_kdbAtHf_smGug0NCviYbZvW_9uGLXLT1LjheMQ-bpBOOtqcD5ln3Uz0aAjS6EALw_wcB
Best, Marni
Figure: Bad Example - Dirty URL with superfluous information
To: Adam Cc: YYY Bcc: ZZZ Subject: Purchase please - new hand dryer Hi Adam,
Here is the link to the new hand dryer that you wanted to see:
Vortex Hand Dryer, Super Quiet motor, 3 Years Warranty OZ2100 $184 (no electrical installation required – plugs in – for the men's bathroom upstairs) https://www.ozwashroom.com.au/hand-dryer-285
Best, Marni
Figure: Good Example – Clean URL that is easy to read and looks much better
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 integratedFigure: 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.
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.
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
