Synapse Docs Style Guide

• Article content should begin with a short summary describing what the page is about.

• Use second person pronouns (you/your/yours) when instructing users, rather than third person.

• When in doubt, consult the Google Developer style Guide

Formatting

• Synapse entity types or features are referred to as proper nouns and capitalized. e.g. File, Project.

• When writing instructions, Synapse buttons or other elements of the UI are emphasized as bold. 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 it is too distracting.

    • Good: “To store Docker images, use the docker push command.”

    • Avoid: “To store Docker images, use the docker push command.”

Capitalization

In document titles and headings, use sentence case. That is, capitalize only the first word in the title, the first word in a subheading after a colon, and any proper nouns or other terms that are always capitalized a certain way.

Even though you're using sentence case, don't put a period at the end of a title or heading.

Terms

• 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.