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.
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.
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.
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.
Write in a way that is compelling, engaging, and direct to get the most out of your content. The secret to this is using an active voice.
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.
When explaining steps in a process. For example, for 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 (there could be bugs!).
They are similar but "Retry" is a more like computer jargon, whereas "Try again" sounds friendlier and more human.
The best way to emphasize your point is to show the pain first, and then the solution. Use "Bad example" and "Good example" with crosses and ticks, respectively, in captions.
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.
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.
Using the wrong kind of dash in the wrong place makes sentencess less clear to the reader. Even though most people might not know the rules - using dashes incorrectly - can make your writing uncomfortble even to people who don't know the rules – it might just 'feel—off'
Using the right kind of dashes (em dash, en dash, and hyphen) in the right places makes your sentence more coherent, correct, and pretty.
Use lowercase after "-" in a text.
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.
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.
With so many different capitalization conventions used in technology names, it can be confusing to know which convention to use for which technology.
According to the Scrum Alliance, "Scrum" is capitalized.
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.