Improve the clarity, consistency, and effectiveness of your technical documentation with these comprehensive rules. From formatting and SEO to ensuring readability and accuracy, these guidelines will help you create top-quality documentation.
SSW Rules are technical documentation presented as practical guidelines that help teams build better software and work more effectively. They capture best practices across coding, architecture, communication, design and project management, making them a living knowledge base that supports consistency, clarity and quality in every project.
This is an example rule + Markdown cheatsheet to give you some guidance around how to write rules and show you the things you can use to format an SSW Rule. For more info see our GitHub Wiki page.
It doesn’t matter what type of information you have, suffering a data loss is frustrating and takes time and money to restore and recover.
Whenever you have to delete content, take an extra step and and paste it into an email thread as a safety step. You should also inform people that care about that content.
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.
When writing any content it is vital you cut unnecessary words to keep the reader interested and focused. This is especially important for dense or technical documentation. Your writing can be less wordy and still get the message across.
Improper spelling, grammar, and punctuation gives a bad impression of your company and can result in your message not being conveyed correctly.
Attention to detail plays a vital role to effective communication. Grammar, spelling, and/or syntax mistakes, though seemingly minor, can significantly affect the clarity and professionalism of your writing.
Clear communication is essential for success, and especially helpful in professional or technical contexts. You should make your content more visually interesting and easier to scan quickly.
Acronyms are a common way to shorten words or phrases, but using niche terms can lead to confusion and misunderstandings. It's important to avoid jargon, especially for those new to a particular field or industry. To ensure clear communication, avoid unfamiliar acronyms where possible and use the full term instead.
Be careful of misunderstanding across English variants.
It's important to avoid culturally specific language that may not translate well globally, especially when a company has international offices, employees, or clients.
If you sign a document and write a date like 2/1/12, you’ve left the door open for trouble. That shorthand can be misread (is it January 2nd or February 1st?) or even tampered with (someone could easily change it to 12/11/2012), and you’d never know.
It's a small habit, but writing dates properly can prevent fraud, confusion, and embarrassment.
Whenever writing numbers, it's generally a good idea to use numerals, especially for complicated numbers. Numerals are more easily noticed when a page is scanned by a user's eye.
Remember to use dividers when referring to large sums or phone numbers.
The English language can be complex, and often the context of a message isn't clear until halfway through or even at the very end. Using prefixes helps surface that context right away.
It's usually easier for users to remember where given information is when it is associated with an image/icon. This is especially true for non-technical people or those who are not very familiar with digital workspaces.
When writing technical instructions, it's important to distinguish UI controls, buttons, and labels from regular text to improve readability and maintain consistency.
We've all missed a piece of a message and found out later that we'd got it wrong. This can lead to miscommunication, mistakes, and lost time. Even worse, when finding out later that someone has misread something, there can be a lot of work to fix! But, there are ways to prevent this.
It's important to clearly differentiate keywords and referenced text from your own content to help readers follow the message and avoid confusion.
Email templates are an awesome way to help people save time writing emails. Often the template needs to indicate a piece of text that should be replaced with custom content. When you need to identify text that should be replaced (e.g. in an email template), it's important to use a consistent way of indicating the replaceable text with a placeholder.
Use a consistent character to make it clear which piece of text should be substituted.
Quotations should not blend into the rest of your message. Whether you're responding to an emailm, IM message, or writing content for the web, formatting quotations clearly helps readers understand what’s being quoted and what's your original content.
The way your inbound links are worded makes a big difference. They play an important factor for search engine results and for the users.
Having descriptive links with relevant words boosts your website SEO, improves accessibility, and gives a more friendly experience to all users.
When you’re sending emails, or pinging someone in Teams, your URLs should be as clean as possible. Having no extra noise ensures that they are easy to read, and it is more aesthetically pleasing.