...
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 pushcommand.”Avoid: “To store
Dockerimages, use thedocker pushcommand.”
...
In section headings, use title case. That is, capitalize every word in the title except for minor words and prepositions.
Do not capitalize entities such as project, table, or file. While this may be occasionally used as a convention 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.
...