Synapse Docs Style Guide

When in doubt, and if not covered below, consult the Google Developer Style Guide.

Why use this guide?

Following this guide is not only important for consistency’s sake, but it will help make your life easier if you need to write/update an article. Following this guide is like using a template. Stick to the rules and you won’t have to wonder if you’re doing things right. It’s all here.

Structure

• Article content should always begin with a context-setting 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.

• If adding a new article or section, aim for a logical structure of information based on what the user might want to read and when. A good strategy to follow is to organize and name your pages according to specific actions that a user may take (I.e. “Finding and Downloading Data”, etc.)

Table of Contents

• Unless a page is super short, it should have a table of contents. 

• With scroll viewport, a table of contents will automatically be created for any headings, using Heading 2 and lower (i.e. Heading 2 ,3, 4, 5). If you use Heading 1, it will not be added to the table of contents. 

• Use Heading 2 for main headings, 3 of subheadings, 4 for sub-subheadings, etc. Headings are super helpful for breaking up content into smaller chunks. This is especially useful when a user may only be interested in one chunk of content and not the rest, since they can easily navigate using the TOC. Try to label your headings based on this.

• A major bonus to this table of contents style is that you can link to specific sections of a page, since TOC headings are assigned their own URL (once published). For example, this section, or even more specifically, this subsection.

Formatting

• 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 the docker 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 (pay extra attention here!)

• In section headings, use title case. That is, capitalize every word in the title except for minor words and prepositions.

• In descriptive text, Synapse entities or features are referred to as common nouns and are lower case. While upper case is sometimes used for entities in developer docs, it is not common for user docs where the audience may be less technical. The repeated emphasis on the same words throughout a sentence or article is distracting and makes the text less readable. The exception to this rule is if you are referring to a specific component, button, or menu within the UI where the term is 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”.

  • Good: “Navigate to the file of interest and then select the File Tools menu.”

  • Avoid: “You can use Sharing Settings to control who can see a File, Table, View, or Project.”

Terminology

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

• Avoid using the term “entity” when possible. Less technical audiences may not be familiar with this concept, so it may cause confusion.

• 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

• Whenever possible, screencaps should be anonymized so that your Synapse username 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.png 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.

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