AuthoringNotes.md

Authoring Notes

Sparse authoring notes and more.

How to Write Good

Markdown

The following topics describe markdown used at Microsoft.

• How to use Markdown
• Markdown Reference for OPS. Markdown extensions designed to provide richer content in docs.microsoft.com.
• How to include code in docs
• VS Code Open In Browser

GitHub

Getting Started

1. Download and install GitHub desktop client at: https://desktop.github.com/
2. Clone https://github.com/Microsoft/BotBuilder-Samples/
3. Clone https://github.com/MicrosoftDocs/bot-docs-pr/
4. Download and install Visual Studio (community version 2017 or higher)
   1. Install ASP.NET and web developer workload. Check the Visual Studio Installe.
5. Download Bot Framework v4 SDK Templates for Visual Studio.
   1. After the download click the .vsix file to install the extension into Visual Studio.

Branches

1. In GitHub select the repository where to create the branch.

2. Assure that master is selected.

3. In the Branch master button, upper left, click the down arrow.

4. In the popup dialog, enter the name of the branch.

5. Click the Create branch button.

   

6. Open your GitHub desktop client, switch to the branch just created.

7. Clone the master branch into the new branch.

8. Start working in this branch.

9. When you reach a meaningful stage, commit the work to the branch.

10. Click the Push origin button.

11. Click the Create pull request button. This opens the remote GitHub Open a pull requet page.

    

12. Enter the needed comments (you can change them later).

13. Enter the assignees.

14. Enter/create related label such as WIP.

15. Click the Create pull request button. The related pull request page is displayed.

    

16. Keep the pull request open to continue the work in the branch.

Review Process

The review process is a crucial step when authoring a document. This section describes a possible way to proceed. We assume that you are using Visual Studio Code to author markdown articles. For more information see How to Compare files in Visual Studio Code ?.

1. Open Visual Studio Code.
2. Author the article. We'll use this file as an example: Review Test File.
3. Save the file.
4. Copy the file and mail it for review.
5. We have made some fictitious changes you can see here: Review Test File Fixes. This file contains the review changes that you need to incorporate in the original file. You might reject the changes, by the way.
6. Open both the original and the reviewed files.
7. In the explorer pane, right click on the name of the original file. In the drop-down select Select for compare.
8. In the explorer pane, right click on the name of the reviewed file. In the drop-down select Compare with Selected.

Create Class Diagrams

You can create class diagrams in VS2019 using the code map tool. For more information,see Map dependencies with code maps.

In order to have the Architecture tab in the task bar do the following:

1. Go to Tools->Get Tools and Featutres...
2. Click the Individual components tab
3. In the Code tools section, check Live Dependency Validation

Bot Core Content

• Docs contributor guide
• Onboarding & admin guide

Tools

• Capture popup menus with the Windows Snipping tool
• Start a chat in Teams
• How to: Add class diagrams to projects
  • How to add a Class Diagram to an ASP.NET Core project in VS 2017?
  • Class Diagrams in VS 2017
• Lorem Ipsum generator
• Visual Studio Code
• Map dependencies with code maps
• Markdown Here
  • Markdown Cheatsheet
• Bot Framework Doc Contributor Guide

Azure

• Azure CLI Reference