Add a text formatting article to the local contributors guide (#2517)

* Start on text formatting article.

* wip

* Update formatting-text.md

* Update formatting-text.md

* Update formatting-text.md

* Update formatting-text.md

* wip

* Update formatting-text.md

* Update formatting-text.md

* Update formatting-text.md

* transient FAQ test

* revert FAQ changes

* Update formatting-text.md

* Update formatting-text.md

* Update formatting-text.md

* Start work on a glossary.

* Update bot-framework-glossary.md

* Update bot-framework-glossary.md

* Update bot-framework-glossary.md

* Added meeting notes

* Update bot-framework-glossary.md

* Update bot-framework-glossary.md

Co-authored-by: Emily Olshefski <[email protected]>

contributor-guide/bot-framework-glossary.md

@@ -0,0 +1,168 @@
+# Bot Framework glossary
+
+Contains a consolidated list of collected terms for the Bot Framework SDK docs, and by extension, the Composer docs. This is not meant to be the definitive source of truth, but notes taken as we hunt down the official terms to use. Meant to be a living document, as definitions and official terms will change over time.
+
+To try to keep this from exploding, the intent to to capture terms that either are not easy to otherwise look up or we are constantly looking up but are not likely to change frequently.
+
+<hr/>
+
+[A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [F](#f) | [G](#g) | [H](#h) | [I](#i) | [J](#j) | [K](#k) | [L](#l) | [M](#m) | [N](#n) | [O](#o) | [P](#p) | [Q](#q) | [R](#r) | [S](#s) | [T](#t) | [U](#u) | [V](#v) | [W](#w) | [X](#x) | [Y](#y) | [Z](#z)
+
+<hr/>
+
+### Resources
+
+These should be considered the sources of truth, and you _should not_ "use Microsoft.com, any other web page, or product UI as a source for product and feature names, capitalization, spelling, and usage".
+
+#### On Corpnet
+
+- [Term Studio][] &mdash; In theory, the source of truth, at least for product names.
+- [Microsoft Cloud Style Guide][] / A–Z names + terms dictionary &mdash; Cloud-specific style guide. Searches here should also pick up terms in the Microsoft Writing Style Guide.
+- [Microsoft Writing Style Guide][] / A–Z word list and term collections &mdash; Microsoft-wide style guide.
+
+[Term Studio]: https://termstudio.azurewebsites.net/default.aspx
+[Microsoft Cloud Style Guide]: https://styleguides.azurewebsites.net/StyleGuide/Read?id=2696
+[Microsoft Writing Style Guide]: https://styleguides.azurewebsites.net/StyleGuide/Read?id=2700
+
+#### On the web
+
+- [American Heritage Dictionary][] &mdash; Source of truth for [most] common (non-Microsoft-specific) terms.
+
+[American Heritage Dictionary]: https://www.ahdictionary.com/
+
+#### Other
+
+When in doubt and we don't have guidance yet, check with an appropriate subject matter expert, and get a second opinion, if the first answer seems odd or otherwise dubious.
+
+- The Connector API team for the Connector REST API, Direct Line, and the Azure Bot Service channel connectors.
+- The Bot Framework SDK dev team for the SDK and the channel adaptors.
+- The Bot Framework Composer team.
+- The Bot Framework Emulator team.
+
+### General entry format
+
+- **Heading**: The complete term to use on first mention, including proper casing and official acronym (if applicable).
+  - **Status**: Indicates whether the term is approved, in Term Studio, or just internal jargon.
+  - **Short form**: If applicable, shorter forms of the term that can be used on subsequent mention in an article, as long as context is clear.
+  - **Definition**: More or less official definition of the term.
+  - **Notes**: Additional notes, if any.
+  - **See also**: Links to related terms.
+
+### Context
+
+For many terms that start with the word Microsoft or Azure, like Microsoft Azure App Service Environment
+
+<a id="a"></a>
+
+## Azure App Service Environment
+
+- **Status**: Approved, in Term Studio.
+- **Short form**: App Service Environment, environment.
+- **Definition**: The Azure App Service feature that provides a fully isolated and dedicated environment for securely running App Service apps at high scale.
+- **Notes**: Don't use ASE as an acronym.
+- **See also**: [Direct Line App Service extension](#direct-line-app-service-extension).
+
+## Azure Bot Service
+
+- **Status**: Approved, in Term Studio.
+- **Short form**: Bot Service.
+- **Definition**: The service that accelerates the process of developing a bot. It provisions a web host with one of five bot templates that can be modified in an integrated environment.
+- **See also**: [Microsoft Bot Framework](#microsoft-bot-framework), [bot service](#bot-service).
+
+<a id="b"></a>
+
+## Bot Framework
+
+See [Microsoft Bot Framework](#microsoft-bot-framework).
+
+## bot service
+
+- **Status**: Approved, in Term Studio.
+- **Definition**: An instance created by the user using Azure Bot Service.
+- **See also**: [Azure Bot Service](#azure-bot-service).
+
+<a id="c"></a>
+<a id="d"></a>
+
+## Direct Line API
+
+- **Status**: Approved, in Term Studio.
+- **Short form**: Direct Line.
+- **Definition**: The API that allows you to enable communication between your bot and your own client application.
+
+## Direct Line App Service extension
+
+- **Status**: Approved, not in Term Studio.
+- **Short form**: App Service extension, extension.
+- **Definition**: Allows clients to connect directly with the host, where the bot is located. It runs inside the same subscription, App Service, and Azure network as your bot and provides network isolation and, in some cases, improved performance.
+- **Notes**: Don't use ASE as an acronym.
+- **See also**: [Azure App Service Environment](#azure-app-service-environment).
+
+## Direct Line Speech
+
+- **Status**: Approved, in Term Studio.
+- **Definition**: The solution used to create a voice assistant with richer and more sophisticated capabilities.
+
+<a id="e"></a>
+<a id="f"></a>
+<a id="g"></a>
+<a id="h"></a>
+<a id="i"></a>
+<a id="j"></a>
+<a id="k"></a>
+<a id="l"></a>
+<a id="m"></a>
+
+## Microsoft Bot Framework
+
+- **Status**: Approved, in Term Studio.
+- **Short form**: Bot Framework, framework.
+- **Definition**: The comprehensive offering to build and deploy high quality bots for users to enjoy wherever they are talking. Users can start conversations with your bot from any channel that you've configured your bot to work on, such as SMS, Skype, Slack, Facebook, and other popular services.
+- **Notes**: Do not shorten to BF.
+
+### Bot Framework CLI tool
+
+- **Status**: tbd
+- **Short form**: CLI.
+- **Definition**: A CLI (command-line interface) for managing Bot Framework bots and related services.
+
+### Bot Framework Composer
+
+- **Status**: Approved, in Term Studio.
+- **Short form**: Composer.
+- **Definition**: The open-source visual authoring tool that is used to build bots.
+
+### Bot Framework Emulator
+
+- **Status**: Approved, in Term Studio.
+- **Short form**: Emulator.
+- **Definition**: The application that allows bot developers to test and debug their bots locally or run them remotely through a tunnel.
+- **Notes**: Do not use "Bot Framework Channel Emulator".
+
+### Bot Framework SDK
+
+## Microsoft Bot Framework Connector
+
+- **Status**: Approved, in Term Studio, potentially stale.
+- **Definition**: The communication service that helps you connect your bot with many different communication channels, such as SMS, email, and Skype.
+
+<a id="n"></a>
+<a id="o"></a>
+<a id="p"></a>
+<a id="q"></a>
+<a id="r"></a>
+<a id="s"></a>
+<a id="t"></a>
+<a id="u"></a>
+<a id="v"></a>
+<a id="w"></a>
+
+## Web Chat
+
+- **Status**: Approved, in Term Studio.
+- **Definition**: The embeddable web chat control for the Microsoft Bot Framework using the Direct Line API.
+- **Notes**: You may need to qualify this term, as there is a Web Chat control (to embed in a web page) and a Web Chat channel (in Azure).
+
+<a id="x"></a>
+<a id="y"></a>
+<a id="z"></a>

contributor-guide/contributor-guide-index.md

@@ -15,6 +15,8 @@ ms.author: tysonn
 - [Contribute to Bot Framework documentation](../README.md)
 - [Content channel guidance](content-channel-guidance.md)
 - [Style and voice](style-and-voice.md)
+- [Formatting text](formatting-text.md)
+- [Bot Framework terms (glossary)](bot-framework-glossary.md)
 
 ## Authoring articles: tools, processes, guidance
 

contributor-guide/formatting-text.md

@@ -0,0 +1,60 @@
+# Formatting text
+
+This article attempts to bring together the sometimes contradictory guidance from the Docs contributors guide and Microsoft Style Guide, and when applicable, our own specific take on it.
+
+## Referenced articles
+
+These are the articles referenced in rough order of relevance
+
+| Last checked | Article | Shorthand |
+|:-|:-|:-|
+| 1/1/2021 | Docs contributors guide / Resources / [Format text](https://review.docs.microsoft.com/en-us/help/contribute/text-formatting-guidelines?branch=master) | Format text |
+|  | MS Style Guide / Developer content / [Formatting developer text elements](https://docs.microsoft.com/en-us/style-guide/developer-content/formatting-developer-text-elements) | Dev text |
+|  | MS Style Guide / Procedures and instructions / [Describing interactions with UI](https://docs.microsoft.com/en-us/style-guide/procedures-instructions/describing-interactions-with-ui) | Describing UI |
+|  | MS Style Guide / Procedures and instructions / [Formatting text in instructions](https://docs.microsoft.com/en-us/style-guide/procedures-instructions/formatting-text-in-instructions) | Instructions |
+|  | MS Style Guide / Text formatting / [Formatting common text elements](https://docs.microsoft.com/en-us/style-guide/text-formatting/formatting-common-text-elements) | Common text |
+| na | None. Agreed upon within the Bot Framework writing team, or based on input from the **Docs Support** Teams team. | The rough date of the last discussion on a specific element. |
+
+## Guidance
+
+| Element | Convention | Example | Source and notes |
+|:-|:-|:-|:-|
+| Code element [language-agnostic] | _Italic_ (when the meaning might be ambiguous) or normal. Use lower case (except where the element name includes a proper noun) and separate words with spaces. Treat this a little bit like a [new term](#new-term). | To receive a simple text message, use the _text_ property of the _activity_ object. | 2018: Decided to use descriptive terms in italic for SDK elements because the names are not identical across languages. However, this means that such text may get localized with formatting. |
+| Code element [language-specific] | `Code`. Match the exact form of the element. In general, qualify what type of element you're talking about, such as namespace, class, method, property, keyword, and so on. Don't add () to the end of a method to indicate that it's a method, unless you need to include the full signature. | The `Attachments` property of the `Activity` object contains an array of `Attachment` objects that represent the media attachments and rich cards attached to the message. | Format text > [Code style](https://review.docs.microsoft.com/en-us/help/contribute/text-formatting-guidelines?branch=master#code-style) |
+| Command-line commands | `Code`, inline or fenced. | Use `dotnet run` to start the bot. | Format text > [Code style](https://review.docs.microsoft.com/en-us/help/contribute/text-formatting-guidelines?branch=master#code-style)<br/>(Fenced code blocks include a copy button but take up more visual space.) |
+| Emphasis | _Italic_. Use sparingly. Do not capitalize a word just for emphasis. | Cybercriminals might call you and claim to be from Microsoft. Be aware that Microsoft will _never_ call you to charge for security or software fixes. | [Common text](https://docs.microsoft.com/en-us/style-guide/text-formatting/formatting-common-text-elements) |
+| <a id="file-names"></a>File names, folder names, and paths | **Bold**. Match the casing of the path. | Update **run.csx** with the following code: | 2018: We wanted some visual distinction that wasn't as jarring as the `code` format. Locallization shouldn't be an issue, since most file names and paths are not translatable. |
+| File extensions | Normal. Lower case. Include the . before the extension name. | An .lu file contains Markdown-like, simple text based definitions for language understanding resources. | [Instructions](https://docs.microsoft.com/en-us/style-guide/procedures-instructions/formatting-text-in-instructions)<br/>When choosing between "a" or "an", assume the dot (.) is unvoiced. |
+| Literals | TBD | TBD | TBD |
+| <a id="new-term"></a>New term | _Italic_. Lower case, unless it is a proper noun. Only italicize on first mention, and include a description or example. | An app runs in an _App Service plan_. An App Service plan defines a set of compute resources for a web app to run on. | Format text > [Italics](https://review.docs.microsoft.com/en-us/help/contribute/text-formatting-guidelines?branch=master#italics) |
+| Package names - TBD | **Bold**. Match the casing of the package name as it appears on the package repository site, such as on [NuGet](https://www.nuget.org/), [npm](https://www.npmjs.com/), and so on. Qualify the name with what type of package it is. | To use dialogs, install the **Microsoft.Bot.Builder.Dialogs** NuGet package. <br><br>OR<br><br> To use dialogs, install the *Microsoft.Bot.Builder.Dialogs* NuGet package. | 2018: Same reasoning as for [file names](#file-names). There is guidance suggesting [italics](https://review.docs.microsoft.com/help/contribute/text-formatting-guidelines?branch=master#code-style).|
+| Sample names | **Bold** on first use. Match the sample name (use the name in the README). | A copy of the **Proactive messages** sample in [**C#**](#), [**JavaScript**](#), or [**Python**](#). | 2018: See [Localization](#localization) note. |
+| UI elements [with a label or hover text] | **Bold**. Match the casing of the element's label or hover text. | In **Solution Explorer**, right-click the project node, and then select **Add** > **New Item**. | Format text > [Bold](https://review.docs.microsoft.com/help/contribute/text-formatting-guidelines?branch=master#bold) |
+| UI elements [without a label or hover text] | _Italic_ on first use, then normal. Lower case. Treat this like a [new term](#new-term). | Both Azure DevOps Services and Azure DevOps Server 2019 use the new navigation user interface, with a vertical sidebar to go to the main service areas: **Boards**, **Repos**, **Pipelines**, and more. To learn more, see [Web portal navigation](#) in Azure DevOps. | 12/2020: The UI element without UI text in this example is the _sidebar_, as opposed to the service areas listed in the sidebar. |
+| URLs [clickable] | Use a [link](https://review.docs.microsoft.com/en-us/help/contribute/links-how-to?branch=master#link-text) with link text that is descriptive [within the context] and does not include additional formatting. Do not use "here" as the link text. Use the title case if using the exact section, article, or TOC title. Consider notifying users if they are leaving a docset. | Knowledge of [Bot basics](https://docs.microsoft.com/azure/bot-service/bot-builder-basics). | [Links](https://review.docs.microsoft.com/en-us/help/contribute/links-how-to?branch=master#link-text) |
+| URLs [clickable, exception] | When including a list of language-specific links to samples, we have been using the language name in **bold** for the link text. Don't include sample after the language name. | A copy of the **Proactive messages** sample in [**C#**](#), [**JavaScript**](#), or [**Python**](#). | 2018: Here, even for screen readers, the context should make the meaning of these links obvious. |
+| URLs [non-clickable] | `Code`. | Enter your bot's URL, which is the URL of the local port, with /api/messages added to the path, typically `http://localhost:3978/api/messages`. | Format text > [Code style](https://review.docs.microsoft.com/en-us/help/contribute/text-formatting-guidelines?branch=master#code-style) |
+| User input | TBD | TBD | TBD |
+
+## Notes
+
+### Icons
+
+re:  Microsoft Style Guide / A–Z word list and term collections / I / [icon](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/i/icon)
+
+[Icons Guidance](https://review.docs.microsoft.com/en-us/help/contribute/markdown-reference?branch=master#icons)
+
+[Test themes and transparency](https://review.docs.microsoft.com/en-us/help/contribute/contribute-how-to-create-conceptual-art?branch=master#test-multiple-themes-and-transparency)
+
+Avoid using the word _icon_ for icons that include a name or hover text.
+To refer to the graphic itself, if there's no other identifying label, use _symbol_, as in _warning symbol_.
+
+**Examples**
+
+- Select **Resources** 📄.
+- Select the warning symbol ⚠.
+- Most apps have their own settings. Look for the gear icon ⚙ in the app.
+
+### Localization
+
+If you choose an alternate text style where code is normally called for, make sure it's okay for the text to be translated in localized versions of the article. Code is the only style that automatically prevents translation. For scenarios where you want to prevent localization without using code style, see [Non-localized strings](https://review.docs.microsoft.com/en-us/help/contribute/markdown-reference?branch=master#non-localized-strings) in the Contributors guide.