Edit

Share via

About wikis, READMEs, and Markdown

  • Article

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

To support your team or contributors to your project, use Markdown to add rich formatting, tables, and images to your team project. You can use Markdown format within a team project wiki, content you add to a dashboard, your team project README file, or other repository README file.

Wiki

Use your team project wiki to share information with other team members. When you provision a wiki from scratch, a new Git repository stores your Markdown files, images, attachments, and sequence of pages. This wiki supports collaborative editing of its content and structure.

Publish existing Git repositories to a wiki

Many teams document their code using Markdown and check in these files along with the code. While Git supports the maintenance and review of such documentation along with standard pull requests, such files present a few challenges to consumers of the content.

  • Readers 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 codes rather than a search experience optimized for searching content.

With the publish code as a 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 content alongside your code base, and lets you selectively publish and update your content to a wiki.

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

Markdown

Markdown 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 provide guidance to your team in the following places using Markdown:

For supported syntax, see Use Markdown in Azure DevOps.

READMEs

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 work within your project. Consider adding the following guidance:

  • Project focus
  • Prerequisites
  • Setting 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

Here are some great READMEs that use this format and speak to all audiences for reference and inspiration: