styles.wiki is a community-driven collection of styleguide rules for various technical domains. "Styles" are submitted as GitHub issues and will appear on this web app.
techwriting.styles.wiki is for technical writing - project documentation, scoping docs, tech specs, RFCs etc.
All styles
Use bulleted lists to break up long sentences
Break up long sentences of continuous points for better readability. This can break up the presentation of densely packed information to make it more digestible. Example Instead of The three main classes of HTTP error status codes are 2xx indicating a successful response, 4xx for a user error and 5xx for a …
Add whitespace
Designers apply whitespace to give their designs "a clean, uncluttered feel". We can apply the same principle in written documents. This does not just mean "break up into lots of paragraphs" - also consider: The spacing between a code block or image, and a block of text. Example Instead of Prefer The spacing be…
Use a monospace font for code snippets
In markdown, you can use single backticks (`) for inline code `like this`. This applies to things like: blocks of code stack traces names of libraries example variable names version ranges ...anything that may appear in a line of code! Markdown For whole blocks of code, you can use triple backticks (```): ``` like thi…
Apply syntax highlighting to code blocks
In markdown, you can add a language modifier after the triple backticks (e.g. ```json) to get syntax highlighting. To get syntax highlighting In Google Docs, you can: paste in code from your IDE; or use an add-on Example ```json { "hello": "world" } ``` Why? Syntax highlighting can help make the code more readable, …
Avoid screenshots of code
Don't embed a screenshot of code - paste in the original code into the body of the document as raw text. To learn how to get syntax highlighting in Google Docs, see #4 Why? Screenshots can't be easily updated. The original author has to go back to their IDE and take a new screenshot. Coauthors would have to …
Provide a summary list ahead of long lists
Ordered lists can be a great way of structuring a large section of a document - for example, the implementation of each milestone may get its own section, with a numbered section header. If the "list" starts to span multiple pages, it's harder for the reader to get an overall sense of how many sections there are, a…
Use correct casing and spelling for technical terms and proper nouns
When referencing technical terms, try and always use its canonical spelling and casing. For example, "GraphQL" should always be written as such - instead of "graphql", "graphQL" or "Graphql" etc. If you're not sure about the spelling of a certain noun, the official homepage of it typically contains the proper spelling …
In a list of points, make a word or phrase bold at the start of each item
Why? Reading through a list can be visually tedious and it may be difficult for the reader to remember all of the points being made. Make the first sentence or phrase a summary. This can be emboldened to make it stand out and easier for the reader to scan through. This helps them summarize the points, which sho…
Avoid temporal information
Avoid temporal information. Content that describes something only relevant today will be less relevant to readers tomorrow. Avoid adding information that is likely to go stale over time, because we then have to commit to keeping it up to date over time. For example, we may want to document a new process after …