About wikis, READMEs, and Markdown

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

You can support your team and project contributors by using Markdown to add rich formatting, tables, and images to your team project. The Markdown format enhances team project wiki pages, content you add to a dashboard, your team project README file, or other repository README files.

Set up a project wiki

A team project wiki lets you share information about your project with other team members. When you set up a wiki from scratch, a new Git repository stores your Markdown (.md) files, images, attachments, and sequence of pages. The wiki supports collaborative editing of its content and structure.

The following links describe the supported features for a team project wiki.

Publish Git repositories to a wiki

Many teams document their code by using Markdown files, which they check in to the repository along with their code. While Git supports the maintenance and review of code documentation files by using the standard pull request process, these files can present challenges to consumers of the content.

• User must often sift through many files and folders to find the content of interest.
• Content lacks organization and structure. There's no inherent page hierarchy to support readers.
• Content versioning isn't supported.
• Searching through content relies on searching the code rather than a search experience optimized for searching content.

With the Publish code as wiki feature, you can publish one or more Git repositories defined in your team project to a wiki. This feature provides a way to maintain your code documentation synchronously with your code base, and lets you selectively publish and update your documentation to a wiki.

There are significant differences between how you manage the content in a wiki for a team project versus wiki pages that you publish from a Git repository. For details, see Publish a Git repo to a wiki.

Enhance project content with Markdown

The Markdown format makes it easy to format text and include images. You can also link to documents within your project pages, README files, dashboards, and pull requests.

You can use Markdown to provide guidance to your team in the following ways:

• Team project wiki
• Code published as wiki
• Dashboard content
• Project page or Welcome pages
• Repository README files
• Pull requests

For supported syntax, see Use Markdown in Azure DevOps.

Add project README files

You can define a README file or multiple files for each repo or team project. Write your README in Markdown instead of plain text. Use README pages to orient contributors to specific information or locations within your project.

Consider adding the following guidance:

• Project focus
• Prerequisites
• Set up the environment
• Tips for getting things done within the project
• Purpose or use of specific files
• Project-specific terms and acronyms
• Workflow guidance about committing or uploading changes and adding branches
• Project sponsors or contacts

README examples

Here are some examples of project READMEs in GitHub that support all audiences for reference and inspiration:

• ASP.NET Core
• Visual Studio Code
• Chakra Core