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, or user inputs. Do not use this to refer to elements of the UI.

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

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

Terms

• Synapse ID should be abbreviated as synID, not synId.

• Terms to avoid in technical writing:

  • Please

  • Easy/easily

  • Simple/simply

  • Latin abbreviations (etc, e.g., or i.e)

Images

• Screencaps should be anonymized so that personal Synapse usernames or other personal identifiers are not visible.