FAQ : Appendix B

Guides that are essential to contributing content are collated on a single page in the Quick Start. Alternatively, choose a specific guide from the left sidebar menu. For example, there are guides in the section Workflow and processes that describe the General workflow, Authoring process, Technical reviews, Instructional design reviews, Content editing, and Testing. Beginning contributors should follow the guides in the section Install software, and then move on to the guides in the section Workflow and processes.

Yes. Most contributors must install software by following the guides in the section Install software. To view the course files on GitHub or AzDevOps, without installing software, follow the guide View course files in web browser. If your project requires converting markdown files into Microsoft Word documents, install the software tools for converting files by following the guides in the section Prepublication preparations.

Ask your project manager where the files for the project you’re working on are stored, and how to access them. The files for most projects will be stored on GitHub, AzDevOps, Teams, or SharePoint. To view markdown files on GitHub or AzDevOps, without installing software, follow the guide View course files in web browser. To edit or add content to files from GitHub or AzDevOps, follow the guides in the section Install software, and then download (clone) the files from GitHub or AzDevOps by following the guide Download course files (clone repo).

Git is system of software tools for compartmentalizing a set of files into a unit called a “repo” (short for repository). Git implements version control by tracking the changes you make to each file in a repo, and Git can create and manage multiple repos. GitHub is a web service for hosting and sharing remote (public and private) repos. AzDevOps is short for Azure DevOps. AzDevOps is a web service for hosting and sharing remote private repos. Terms and concepts, including Git, GitHub, and AzDevOps, are explained in the guide Terminology and concepts, and in the Glossary.

Git allows you to compartmentalize a set of files on your computer into a unit called a “repo” (short for repository. For example, the set of files for the course you’re working on can be contained within a Git repo. Git implements version control by tracking the changes you make to each file in a repo. Terms and concepts, including repo, are explained in the guide Terminology and concepts, and in the Glossary. A repo on your computer or network is called a local repo. A repo on another computer, like on GitHub’s servers, is called a remote repo.

Make a local repo by downloading (cloning) a GitHub or AzDevOps repo by following the guide Download course files (clone repo). For more information, refer to the GitHub documentation page Creating, cloning, and archiving repositories.

To download (fork) a repo, refer to the guide Fork a repository. For more information, refer to the GitHub documentation page Forking projects, and to the Microsoft Documentation article Forks overview.

To download (clone) a GitHub or AzDevOps repo, follow the guide Download course files (clone repo). For more information, refer to the GitHub documentation page Creating, cloning, and archiving repositories.

Forks and clones are copies of a GitHub or AzDevOps repository (repo). Cloning copies the repo onto your computer. Forking copies the repo into your GitHub or AzDevOps user account. You can clone a fork to get the fork onto your computer. For more information, refer to the guide Fork a repository.

To fix a cloning or forking error, refer to the guide Fix cloning errors.

To create a new branch, follow the guide Create new branch.

To get (pull) the latest files from GitHub or AzDevOps, follow the guide Update branch (pull).

To delete a branch, follow the guide Delete branch.

To recover a deleted branch, follow the guide Recover deleted branch.

To change/ switch between branches, follow the guide Switch branches.

To write in markdown, follow the guide Add/ edit markdown in VSC. Make sure that the markdown you write adheres to the markdown syntax described in the guide Markdown syntax guide.

To create a new markdown file, follow the guide Create new markdown file in VSC.

Preview a markdown file in Visual Studio Code (VSC) using the Open Preview to the Side icon. Use the Open Preview to the Side icon to open a rendered version of your markdown file in a VSC preview tab, alongside the VSC editor tab. The shortcut keys CTRL + SHIFT + M also toggle VSC Preview to the Side mode on and off. To toggle a “full-window” markdown preview on and off, use the shortcut keys CTRL + SHIFT + V. Previewing in VSC is described in the guide Add/ edit markdown in VSC. For more information about VSC shortcut keys, refer to Key Bindings for Visual Studio Code.

To add images into a markdown file, follow the guide Add/ edit images in VSC.

For each image link you add into a markdown file, you must upload a corresponding image file (PNG). Upload the image file on the filepath that you specified in the image link text. If necessary, rename your image file according to the filename you specified in the image link text. Most projects use a designated image storage directory for image files (media). Make sure that the image link text in your markdown file is pointing to the correct image storage directory. Verify that the image file you’re linking to is present, and stored in the correct directory. Check that the name of the image file matches the filename used in the image link text. Add images into a markdown file by following the guide Add/ edit images in VSC.

The markdown syntax for adding tables into a markdown file is described in the guide Markdown syntax guide.

Checking that computer programming code and encoded text, like markdown, conforms to the correct syntax is called linting. A software tool that performs linting is called a linter. Terms and concepts, including linting and linter, are explained in the guide Terminology and concepts, and in the Glossary.

Fix a linting issue by following the guide Fix linter issues.

Send your files for review by following the guide Send (push) files. The requirements for sending files for review depend on the type of review you’re requesting. The requirements for sending files for review are described in the section Workflow and processes. There are guides that describe the General workflow, Authoring process, Technical reviews, Instructional design reviews, Content editing, and Testing.

To invite a collaborator to a GitHub repo or fork, refer to the guide Invite collaborator.

A pull request (PR) is a request to approve merging (combining) the contents of one branch into another. For more information about pull requests, refer to the guide Pull requests overview, and the GitHub documentation page About pull requests. Terms and concepts, including pull request, are explained in the guide Terminology and concepts, and in the Glossary.

To create a new pull request, follow the guide Create pull request.

When you create a pull request (PR), keep the PR open (don’t merge the PR). Keeping the PR open allows you to push subsequent file changes from your local branch “up” to GitHub or AzDevOps. Any additional changes that you push from your local branch will be “rolled into” your open PR. For more information about pull requests, refer to the guide Pull requests overview.

To merge a pull request, follow the guide Merge a pull request.

A merge conflict is an error caused by attempts to merge branches that contain incompatible versions of the same file. To fix merge conflicts, follow the guide Resolve merge conflicts. Terms and concepts, including merge conflict, are explained in the guide Terminology and concepts, and in the Glossary

To fix merge errors/ conflicts, follow the guide Resolve merge conflicts.

To convert a markdown file into a Microsoft Word document, follow the guide Convert markdown to doc.

Yes. Install the required software tools by following the guide Setup file conversion tools.

Check the links in the guide Links to useful resources, or ask your project manager for help.