This style guide contains a set of standards for the writing and designing of technical documentation for Symbl.ai. The aim is to bring a consistent tone and style to our documentation so that it is easier for our users to understand information.
These guidelines apply to Symbl product guides, references, what's new, and tutorials.
Symbl.ai uses sentence-style capitalization, which implies everything is lowercase excluding the first word and proper nouns, which includes brands, products, and services. (For customers to find it clear to identify, locate, and purchase them, and reserve capitalization for only product and service names.)
Follow these 4 Guidelines in Symbl.ai content:
Always capitalize the first word of a sentence. That means to Capitalize the first word of every sentence, heading, title, UI name, or standalone phrase.
For example,
- An action item is a specific outcome recognized in the conversation.
- Topics are key drivers of the conversation.
Capitalize proper nouns: name for a particular person, place, or thing. Names are proper nouns. The names of programs, gadgets, companies, and software are also proper nouns, so you should capitalize them, too.
For example,
- Symbl offers a comprehensive suite of APIs.
- Symbl's Streaming API is based on WebSocket protocol.
In most titles and headings, you should use sentence-style capitalization: capitalize the first word and lowercase the rest.
Exceptions include Proper nouns, including brand, product, and service names, which are always capitalized. If a title or heading consists of a colon, capitalize the first word after it.
- Don't capitalize a, an, or the unless it's the first word.
- Don't capitalize prepositions of four or fewer letters (such as on, to, in, up, down, of, and for) unless the preposition is the first or last word.
- Don't capitalize and, but, or, nor, yet, or so unless it's the first word or the last word.
- Capitalize the first word of labels and terms that appear in UI and APIs unless they're always lowercase (for example, fdisk).
- In programming languages, follow the traditional capitalization of keywords and other special terms.
For example,
- Transcribe Speech-to-Text in Real-Time
- Topics API- Extracting Relevant Topics
It's okay to use italic sparingly for emphasis. The Chicago Manual of Style has a note (7.48) on capitalization for emphasis, affirming:
“Capitalizing an entire word or phrase for importance is rarely suitable. Suppose capitals are wanted–in dialogue or in representing newspaper headlines. For example, small caps rather than full capitals look more graceful.”
To show emphasis on a particular word or phrase, we recommend using italics. This lets you understand that the author is trying to distinguish this word or phrase from the rest of the text because it appears different. Additionally, it has a more professional and "graceful" emphasis that doesn't seem like "yelling."
For example,
- "DO NOT copy-paste this code."
- "This function STOPS the servers."
A person is a category used to differentiate between:
-
those speaking
-
those being addressed
-
those who are neither speaking nor being addressed (i.e., everybody else).
These three categories are called the first, second, and third person. They are ways of describing points of view.
- First-person is the I/we perspective.
- Second-person is the you perspective.
- Third-person is the he/she/it/they perspective.
Follow these 3 Guidelines in Symbl.ai content:
The second-person point of view refers to the person (or people) being spoken to. This is the “you” perspective. The biggest sign of the second person is the practice of second-person pronouns: you, your, yours, yourself, yourselves. The second-person point of view is usually used to give directions, offer advice, or explain. This perspective allows you to connect with your audience by focusing on the reader and treating them with a compassionate, friendly human tone.
For example,
- To begin, get your API Credentials from Symbl Platform. Using these credentials, you can then generate the Access Token to invoke Symbl API calls.
- You can choose to tune your Summary Page with query parameters in order to play with different configurations and see how the results look.
Use first person (usually I or me) only when you need to write from the customer's point of view. The first-person point of view is more personal than the three points of view. Using I or We gives you the chance to show off your personality as a business owner or establish a clear voice for your brand. This point of view helps build trust with consumers, as any text will read as if it is coming straight from you.
For example,
- Alert me when a new Symbl update comes in. (checkbox text)
- I want to be part of the Symbl slack feedback team.
A grammatical classification of pronouns and verbs used by the speaker to refer to or speak about themselves with others. First-person plural, which often uses the pronoun we, can feel like an intimidating corporate presence which is the exact opposite of Symbl's own modern voice. It's OK if you use phrasing like "we recommend" if it helps you avoid awkward phrasing like "it's recommended", but write around it if you can. Try and keep the focus on the customer, not Symbl itself.
For example,
- The Management API allows you to access and manage various resources against your Symbl account. (Instead of Symbl’s Management API …)
- The Summary UI provides users with a translated meeting summary page with transcript, attendees, topics, action items, follow-ups, and more.
A practical definition for the word "modify" is to change or to alter something. This meaning is the same when considering the purpose of modifiers within a sentence.
A modifier modifies a word/phrase/clause in a sentence to add emphasis, explanation, or detail. Modifiers are descriptive words, such as adverbs and adjectives. Modifier phrases, such as adjective clauses and adverbial phrases, also exist and descriptive adjectives and adverbs.
For example,
- Pre-Built UI is an interface for users to interact with Symbl's APIs output and understand the conversation better.
Follow these 2 Guidelines in Symbl.ai content:
A misplaced modifier is a kind of modifier that is placed far too away from the word, phrase, or clause it is meant to modify and, as a result, appears to be changing something else entirely.
A misplaced modifier can be fixed by removing and moving it to connect to the right subject.
For example,
- Currently, this utility only supports one feature.
A dangling modifier happens when the subject of a modifier is missing from the sentence.
Dangling modifiers usually take the form of an introductory phrase accompanied by a clause that doesn't state the intended subject.
For example,
- There are repositories that can’t be removed on the drive.
Verbs represent external actions (run, jump, work) and internal (love, think, consider). Verbs determine what the subject is doing or feeling, even if they're just being. Verbs are the only type of word that's absolutely essential to make a sentence.
Follow these 4 Guidelines in Symbl.ai content:
In the present tense, the action is occurring now. The present tense is usually simpler to read and understand than the past or future tense. It's the most suitable choice for most of the content.
For example,
- Symbl's APIs let you generate real-time Sentiment Analysis, Action Items, Topics, Trackers, Summary, and much more in your applications.
The mood of a verb states the writer's intent. Most of the time, it's better to use the indicative mood. An indicative mood is a verb form that gives a statement or asks a question. It's crisp and straightforward without being bossy. Don't switch moods within a sentence.
For example,
- The action items provide you with insights into 'who has to do what, by when.'
When the subject of a sentence does the verb's action, it's called Active voice. Simply put, it tells what a person or thing does. The sentence is direct, strong, and easy to read. The active voice describes a sentence where the subject performs an action stated by the verb.
For example:
- Symbl recognizes if an action item has a connotation or nature of language.
Verbs and subjects must agree with one another in number. Hence, if a subject is singular, its verb must also be singular; if a subject is plural, its verb also needs to be plural. No matter what tense you use, your verb has to match the number of the subject. Simply put, singular subjects conjugate verbs differently than plural subjects.
Often, you either add -s to the end of the verb or you don't. However, more advanced tenses with auxiliary verbs can get tricky—both be and have are irregular verbs, so you have to pay close consideration to use their suitable forms even when they're not the main verb.
For example,
- Symbl uses different APIs to analyze conversation data.
Lists are an excellent way to present complex content in a way that's simple, easy, and straightforward to study.
Lists operate best when they have two to seven items. Each item should be reasonably short so that the reader can see at least two or three list items at a glimpse. It's OK to have a couple of brief paragraphs in a list item, but you shouldn't exceed that length too much.
Follow these 5 Guidelines in Symbl.ai content:
You should make sure the concept and purpose of the list are clear and straightforward. Introduce the list with a title, a complete sentence, or a small bit that concludes with a colon.
If you introduce a list with a title, don't use descriptive text after the title. Additionally, don't use a colon or period after the title.
For example,
- Response Body Parameters
- Query Params
You should begin each piece of item in a list with a capital letter unless and until if there's a reason not to (Note: it's a command that's always lowercase). If needed, rewrite all the list items so that all items begin with capital letters or all items begin with lowercase words.
For example,
- cURL (command)
- Sentiment
To learn more, go to the Capitalization section.
A set of items in a bullet point list is neither a sequence nor an option. Use a bulleted point list for items that have something in common but don't necessarily need to appear in a particular order. Bullet points can work as a point of entry for readers, a mode of emphasis, or a way to indicate importance and value.
They can split up long text paragraphs and add variation to a body of work while giving your reader an easy source of quick information. Bullets are clear to spot, short, quick to read, and the information they contain is much easily remembered.
For example,
- Speaker Ratio: The speaker ratio is the total ratio of a speaker versus another.
- Talk time: Talk time per speaker.
- Silence: Indicates the time during which none of the speakers spoke anything.
Numbered lists are an elegant way of using the natural sparsity of data within a business. The numbered list represents a hierarchy. You should use a numbered list for sequential items (like a process or a step-by-step method) or prioritized items (like a list of top 10).
For example,
- Get Symbl Authentication 🔐
- Submit your Audio file 🎤
- Receive Speech to Text & Conversational Action Items 🎁
In either a bullet point or a numbered list, end each item with a period only if any item produces a complete sentence when combined with the introduction of the list that leads to the colon.
Additionally, follow these Don'ts:
- Don't use a period if all items have three or fewer words or if the items are headings, subheadings, UI labels, or strings.
- Don't use commas, semicolons, or conjunctions (and, or) at the end of list items.
- Don't use a period if the item consists of a single word.
- Don't use a period if the item doesn't include a verb.
- Don't use a period if the item is entirely in code font.
- Don't use a period if the item is entirely linked text or a document title.
For example,
- If you want to learn more, check out Introduction to Conversation API.
- If you want to try more APIs, click on Get Topics, Get Questions, Get Entities, etc. in the Conversation API tab in Postman.
To write clear and accurate instructions, first, make sure you understand precisely how to complete the task. Follow and perform your own instructions exactly to make sure they will complete the task successfully.
Follow these 4 guidelines in Symbl.ai content to help you create precise, easy-to-follow instructions, whether you're writing simple, single-step, or complicated processes that consist of multiple steps:
Complicated instructions often consist of multiple steps formatted into a numbered list. For multiple-step step instruction in numbered lists, you should consistently format the steps so customers can find them quickly and can easily grasp them.
You should consider using a title to help clients find the instructions instantly. Use the title to tell clients what the instructions will assist them to do.
For example,
- To create a Symbl account
Every step you write should be action-active. It shows your users precisely the action they need to take to complete a step of the given task.
-
Apply the imperative verb forms. In the step-by-step instructions, users want you to tell them what to do.
-
Use consistent sentence structures, such as using a phrase when you want to tell the customer where to begin. The rest of the time, begin each sentence with a verb.
For example,
- On the ribbon, go to the Design tab.
- Open Photos.
- For Alignment, choose Left.
-
Word your instructions in phrases of what someone needs to do, not what someone must think or know. Usually, include actions that achieve the end of a step, such as OK or SEND buttons.
For example,
- In the response body, check if you have received the conversationID.
The pronoun "you" enables you to address your reader directly and can avoid confusion. When using the pronoun "you", the user knows precisely what they must do to perform the task and doesn't have to speculate.
For example,
- In this guide, you will learn how to get started with Symbl's native Streaming API.
Shorten a simple series of instructions by using right-angle brackets.
Add a space before and after each bracket, and you shouldn't make the brackets bold.
For example,
- Go to Settings tab > API Keys.
Symbl’s Styleguide practices US English which has many dialects and variations depending on geography, but for most purposes, use "General American" English.
Follow these 3 main guidelines in Symbl content, when writing or editing in American English:
For example,
- Use "analyze" not "analyze."
- Use “strategize” not “strategize.”
For example,
- ad hoc
- de facto
For example,
- e.g. instead use - for example
- i.e. instead use - that is
- viz. instead use - namely
- ergo instead use - therefore
Exception: It's OK to use etc., in certain situations where the space is limited and restrictive.
The following writing style guide documents were referred to while creating this document: