As a contributor to Docs content you will interact with multiple tools and processes, allowing you to work in parallel with other contributors on the same project, potentially the exact same content, even at the same time. This is all enabled through Git and GitHub software.
Git is an open-source version control system, which facilitates this type of project collaboration through distributed version control of files that live in repositories. In essence, Git makes it possible to integrate streams of work done by multiple contributors over time, for a given repository.
GitHub is a web-based hosting service for Git repositories, such as those used to store Docs.Microsoft.Com content. For any given project, GitHub hosts the main repository, from which contributors can make copies for their own work (which you will learn about in Setup your local repository). The OPS platform pulls from several main Docs repositories when publishing content to Docs.Microsoft.Com.
If you're familiar with centralized version control systems (such as TFS, SharePoint or Visual SourceSafe), you will notice that Git has a unique contribution workflow and terminology to support its distributed model. For instance, there is no file locking that is normally associated with check-out/check-in operations. As a matter of fact, Git is actually concerned about changes at an even finer level of granularity, comparing files at a byte-by-byte level. Git also uses a tiered structure to store and manage content for a project :
- Repository - also known as a repo, this is the highest unit-of-storage. A repository contains one or more branches.
- Branch - contains the actual files/folders that make up a project's content set. Branches are used for separation of streams of work (typically referred to as versions), and contributions are always made/scoped to a specific branch. All repositories contain a default branch (typically named 'master') and one or more branches destined to be merged back into the 'master' branch. The 'master' branch serves as the current version and "single source of truth" for the project, and is the parent from which all other branches in the repository are created.
Contributors interact with Git to update and manipulate repositories at both the local and GitHub level:
- Locally through tools such as the Git Bash console, which supports Git commands for managing local repositories and communicating with GitHub repositories
- Via www.github.com which integrates Git to manage reconciliation of contributions flowing back into the main repository.
Although Docs guidance is based on using GitHub, some teams use Visual Studio Team Service (VSTS) to host Git repositories. The VS Team Explorer client provides a GUI for interacting with VSTS repositories, which is an alternative to using Git commands through a command line.
Also, many of the guidelines below were developed as best-practices from years of experience in hosting Azure service content in GitHub, and may be required in some Docs repositories.
All workflows begin and end at the GitHub level, where the main repository for any given Docs project is stored. As mentioned earlier, contributors create copies for their own use, which are distributed out across multiple computers, and eventually reconciled later back into the project's main GitHub repository.
Repository conventions and best practices
Many projects that publish to Docs.Microsoft.Com use a separate private GitHub repository for internal contributors, and a replica public GitHub repository for external contributors. Typically, private repositories use the same name as the corresponding public repository, but have a "-pr" suffix.
For teams that don't support a private repository, all contributions are made to the sole public repository. If available though, internal contributors should always contribute to the private repository, which is eventually reconciled with the public version through regular synchronization.
As mentioned earlier, a project's default/'master' branch serves as the current version of content for the project. The content in the master branch (and branches created from it) is loosely aligned with the organization of the articles on the corresponding Docs pages. Subdirectories are used for separation of like content (such as services), media content (such as image files), and "include" files which enable reuse of content.
You will typically find a main "articles" directory off the root of the repository, which contains a set of subdirectories with articles formatted as Markdown files that use an .md extension. Some repositories that support multiple services use a generic
/articles subdirectory, such as the https://github.com/microsoft/Azure-Docs repository. Others may use a service-specific name, such as the https://github.com/microsoft/IntuneDocs repository which uses
Within the root of this directory, you can find general articles that relate to the overall service or product. And typically, you can then find a another series of subdirectories, which match the features/services or common scenarios. For instance, Azure "Virtual Machine" articles are in the
/virtual-machines subdirectory, the Intune "Understand & Explore" articles are in the
/understand-explore subdirectory, etc.
As mentioned, each article directory also contains a
/media subdirectory for corresponding media files, inside which are images used by articles that have image references.
See Adding static art to your content for additional guidance.
Whenever we have reusable content that is shared across two or more articles, it is placed in an
/includes subdirectory off of the main articles directory. In the Markdown file that wishes to use the include file, a corresponding "include" Markdown extension is placed in the location where the include file needs to be referenced.
See How to use Markdown - Includes for additional guidance.
Markdown file template
For convenience, the root directory of each repository typically contains a Markdown template file named
template.md, which you can use as a "starter file" if you need to create a new article for submission to the repository. The file contains:
- A metadata header at the top of the file, delineated by two, 3-hyphen lines, and containing the various tags used for tracking information relating to the article. Article metadata enables certain functionality, such as author attribution, contributor attribution, breadcrumbs, article descriptions, and SEO optimizations as well as reporting processes used by Microsoft to evaluate the performance of the content. So the metadata is important!
- A "Metadata" section that describes the various metadata tags and values. If you're unsure of the values to use for the metadata section, you can leave them blank, or comment them with a leading hashtag (#) and they will be reviewed/completed by the pull request reviewer for the repository. This is covered in more detail in How to write metadata
- Various examples of using Markdown to format the elements of an article.
- General instructions on the use of Markdown extensions, which can be used for various types of alerts.
- Examples of embedding video using an iframe.
- General instructions on the use of docs.microsoft.com extensions, which can be used for special controls such as buttons and selectors.
A pull request provides a convenient way for a contributor to propose a set of changes, to be applied to the default branch. The changes (also known as commits) are stored in a contributor's branch, allowing GitHub to first model the impact of merging them into the default branch. A pull request also serves as a mechanism to provide the contributor with feedback from a build/validation process, the pull request reviewer, to resolve potential issues or questions before the changes are merged into the default branch.
There are a couple of different ways of contributing by pull request, depending on the size of changes you would like to propose. We will cover this in detail later, in the GitHub workflow sections of this guide.