When in doubt, and if not covered below, consult the Google Developer Style Guide
Structure
Article content should begin with a short summary describing what the page is about, what the reader will learn, or what the reader should be able to do after reading the article.
Formatting
Avoid excessive capitalization in your writing, as the repeated emphasis makes the text less readable for most audiences and interrupts the text flow.
In descriptive text, Synapse entities or features are referred to as common nouns and not capitalized.
Good: “A folder can contain multiple files”.
Good: “A wiki is a virtual notebook where you can keep track of information about a project”.
Avoid: “You can use Sharing Settings to control who can see a File, Table, View, or Project.”
When writing instructions that specifically refer to specific elements of the UI, such as Synapse buttons, tabs, menus, or pages, emphasize these terms in bold and capitalize to match how they appear in the UI. E.g. “Click the File Tools menu”.
Code formatting:
Use this to refer to specific synIDs, file names, file extensions, class names, actual code, or user inputs. Do not use this to refer to elements of the UI, as the extra emphasis can be distracting.
Good: “To store Docker images, use the
docker push
command.”Avoid: “To store
Docker
images, use thedocker push
command.”
Voice
Use second person pronouns (you/your/yours) when instructing users, rather than third person.
Aim for a voice and tone that is respectful, friendly, and conversational. Our docs should be approachable and not too formal.
Aim for sentences that are simple, short, and not overly wordy. Remember that not everyone who reads our docs is a native English speaker.
Aim for inclusive language at all times. See the inclusive language section of the Google Developer Style Guide for tips.
Capitalization
In section headings, use title case. That is, capitalize every word in the title except for minor words and prepositions.
Terminology
Synapse ID should be abbreviated as synID, not synId.
Terms to avoid in technical writing:
Please - wordy and usually unnecessary in instructions
Easy/easily - it might be easy for you, but not to someone else
Simple/simply - it might be simple for you, but not for someone else
Latin abbreviations (etc, e.g., or i.e) - these reduce readability of an article, especially for non-native English speakers
Images
Screencaps should be anonymized so that personal Synapse usernames or other personal identifiers are not visible.
Name the image with a short description of the component you are illustrating, separated by hyphens. For example,
report-violation-footer
to show a screencap of the link to report a violation in the footer of the Synapse web UI.
Release Notes
New features and improvements: use present tense for describing how the product currently works and behaves ("You can now..."). The fact that work was done is implied and not very interesting. Focus on value add and how Synapse is better/faster/easier to use/etc.
Bug fixes: use past tense when describing the issues that the release is solving ("The flux capacitor wasn't reacting to stimuli"). Avoid the term “bug” when describing a fix.