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.