Manage your project documentation and collaboration

0

Azure DevOps has built-in Wiki support, which provides great flexibility to document the entire project from a single location. There was a time when your documentation was a Microsoft Word document on a file server, which in most cases only the author could remember where and how to use it. Using Azure DevOps, we can control the entire project, document, store files, track changes, and have automatic build and releases on a single platform available on the internet and running with your Windows, Linux and Mac the same way.

The Azure DevOps wiki uses the Markdown language, which was created in 2004 by John Gruber in collaboration with Aaron Swartz, and it has been used in GitHub and Azure DevOps.

The language is not a complete language intended to replace HTML. The goal was to keep it easy to write and read, and there’s a syntax that emulates the most common HTML tags. We’ll see some examples of markup language, and after that, we’ll be ready to create and format our documentation.

It’s important to remember the hierarchy in Azure DevOps. You can have several organizationsand each organization can contain several projects. Every project has a Wiki. The boundaries of a Wiki are at the project level, not at the organization level. Keep this in mind when planning your documentation structure.

Markdown Language Summary

The following summary may help you understand the differences between markdown language and HTML. Start typing on the Azure DevOps Wiki page, and as you need formatting resources, see the table below.

You will quickly write in demarcated language. Just allow some time to memorize the characters required to format the text.

Article HTML equivalent Markdown language
Title

Title H1

# Title H1
Title*

Title H2

## Title H2
Horizontal line

—-

Bold text Bold text **Bold text**
Text in italics Text in italics *Text in italics*
Strikethrough text Strikethrough text ~~Text typed~~
Estimate > Quotation Level 1
Estimate >> Quotation level 2 (indented)
Connections Azure portal [Azure Portal](http://www.azure.microsoft.com
Coded Get-AzVM “”

""

Picture ![Azure Map](http://address.ca/img.svg)
Unordered list
  • Item 01
– Item 01
Ordered list
  1. Article number 01
1. Item numbered 01

* Title can be up to H6 in HTML and in Markdown we represent with six ######

We'll cover the details in Azure DevOps in our next section, but for now we can see on the left side the markup language code and how the output would be on the right side. This is going to be the experience of the user reading the document.

Create your first AzureDevops Wiki

By default, any new project has no wiki configured, and we can create them in two different ways: WikiProject or one Wiki as code. We can also combine them to enjoy both worlds.

Let's start creating a WikiProject, which creates a Git Repo to store all Wiki information, including .md files, images, etc. Although it's a repository, it's hidden, which means you can't access it through the repositories or even the project settings.

If you're as curious as I am, you can go to this website: https://dev.azure.com///_git/.wiki (Item 1). The main branch of this repository is called .wiki (item 3) and we can see that each page created through the portal is an individual .md file (item 2)

azure devops wiki

To note: As of this writing, there is no easy way to remove a Wiki project. The result will be the editor to create a new page, where we can start writing in our markdown language to begin our project documentation.

azure devops wiki

Using the Azure DevOps portal to manage your Wiki is easy. On the left side, we can create a page using the New page (Item 1) and the new page will be added at the same level as the pages listed above (parent level).

We can also create subpages to an existing page, and it helps to nest the documentation on the same thread. To do this, click on the ellipse on the desired page (item 2), and click on Add a subpage (Item 3).

In the same place, we can change the order of the pages by dragging and dropping them as we see fit.

the Insight article provides an overview of the project, including statistics, members, and a brief description of the project, which can be included in a wiki.

The integration is easy to implement. Log in to the Azure DevOps portal, click Insightand then + Add project description button. In the new panel, provide a brief description, select either Readme File or wiki. In this section, we will choose the wiki (Item 3), and the first page (which should be the main page or homepage) will appear, click Save (Item 4).

Now the documentation will be on the front page of our Azure DevOps portal. A simple visual aid that will help you remember is that the first page always has a Residence icon associated with it.

Important note: The first page of the Wiki will always be displayed. If you change later, the change will automatically reflect on the main page.

azure devops wiki

Added Wiki-as-a-code

By default, when creating new repositories, the option to add a README.md is set automatically, and it is a file that can be written to markdown language the same way we configure our pages in the WikiProject.

We can see this in action by looking at any existing repository. In the image below, we can choose the /README.md repo to keep the documentation up to date.

azuredevops wiki

If the team decides to update the documentation at the repository level, we can take advantage of this process and integrate it into the current version wiki.

The process for adding code as a Wiki is as follows: Click Insight (Object 1), wiki (Item 2), click the drop-down menu on .wiki (Item 3), then click Publish the code as a Wiki (Item 4).

In the new panel, select the depositthe branch, the folder (by default the README.md is at the root), and define a Wiki name (we will use the name of the current repo appended by the -Wiki suffix). Click on Publish.

When we open Wiki (item 1), we can navigate between the Wiki project (item 2) or select from the Wiki code which was added previously (point 3). After choosing a WikiCode, all files with .md extension will be listed, click on them, and the contents will be displayed on the right side.

azure devops wiki

By integrating both methods, we can have a WikiProject to be the main page for your project and use the actual README.md on your repositories to have more concise and specific information about each workload/service in your current project.

Azure DevOps Wiki: Getting Started

So, now you know the basics of markdown language, how to manage pages in your brand new Azure DevOps Wiki and the differences, and how we can integrate both Wiki Code and WikiProject.

Now it's your turn to start integrating Wiki into your Azure DevOps project!

Featured Image: Shutterstock

Share.

About Author

Comments are closed.