Added the styleguide and moved readme, CoC (#364)

styleguide.md

@@ -0,0 +1,389 @@
+# Symbl Documentation Styleguide
+
+
+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 are applicable to our product guides, references, changelog, and tutorials.
+
+
+## Capitalization
+
+***
+
+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:
+
+
+### 1. Capitalize the First Word of a Sentence
+
+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._
+
+
+### 2. Capitalize Names and Other Proper Nouns
+
+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._
+
+
+### 3. Capitalize Most Words in Titles
+
+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_
+
+
+### 4. Don't use all uppercase for emphasis 
+
+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."_
+
+
+## Grammar and Parts of Speech 
+
+***
+
+## Person
+
+A person is a category used to differentiate between:
+
+1. those speaking
+
+2. those being addressed
+
+3. 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:
+
+
+### 1. Use second-person
+
+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._
+
+
+### 2. Use first-person accurately 
+
+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._
+
+
+### 3. Avoid the first-person plural
+
+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._
+
+
+## Dangling and misplaced modifiers
+
+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:
+
+
+### 1. Strictly avoid misplaced modifier
+
+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._
+
+
+### 2. Strictly avoid dangling modifier
+
+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
+
+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:
+
+
+### 1. Use present tense verb 
+
+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._
+
+
+### 2. Use the indicative mood of a verb
+
+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.'_
+
+
+### 3. Use Active voice
+
+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._
+
+
+### 4. Apply Subject-verb agreement
+
+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
+
+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:
+
+
+### 1. Introductory paragraph
+
+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_
+
+
+### 2. Implement Capitalization
+
+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.
+
+
+### 3. Use a Bullet-point list
+
+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._
+
+
+### 4. Use Numbered lists
+
+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,
+
+1. _Get Symbl Authentication 🔐_
+2. _Submit your Audio file 🎤_
+3. _Receive Speech to Text & Conversational Action Items 🎁_
+
+
+### 5. Mind the Punctuation
+
+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.](https://docs.symbl.ai/docs/conversation-api/introduction)_
+* _If you want to try more APIs, click on **Get Topics**, **Get Questions**, **Get Entities**, etc. in the **Conversation API** tab in Postman._
+
+
+## Procedures and Instructions
+
+***
+
+## Writing Step-by-Step Instructions
+
+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:
+
+
+### 1. Format Multiple-step instructions consistently
+
+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_
+
+
+### 2. Start each step with a verb
+
+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](https://docs.microsoft.com/en-us/style-guide/grammar/verbs). 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,
+
+    1. _On the ribbon, go to the **Design** tab._
+    2. _Open **Photos**._
+    3. _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._
+
+
+### 3. Write from a second-person point of view
+
+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._
+
+
+### 4. Shorten a simple series of instructions 
+
+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**._
+
+
+## Word Choice
+
+***
+
+
+## Use US spellings and avoid non-English words
+
+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:
+
+
+### 1. The spelling of English words varies by locale; use the US spelling. 
+
+For example,
+
+* _Use "analyze" not "analyze."_
+* _Use “strategize” not “strategize.”_
+
+
+### 2. Avoid non-English words or phrases.
+
+For example,
+
+* _ad hoc_
+* _de facto_
+
+
+## 3. Avoid Latin acronyms for general English phrases. 
+
+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.
+
+
+## References
+
+***
+
+The following writing style guide documents were referred to while creating this document:
+
+* [Microsoft Styleguide](https://docs.microsoft.com/en-us/style-guide/welcome/)
+* [Google Developer Documentation Styleguide](https://developers.google.com/style)