Azure DevOps 101: Wiki

In the latest post in my Azure DevOps 101 series, we take a look at the wiki functionality within Azure DevOps. This feature provides a great way to share information with your project team and stakeholders.

First of all, two ways exist to create a wiki, either directly in the interface, or by referencing a Git repository with your files in. The experience is slightly different between the two, however this is purely because you edit files in the repository or directly in the browser. Microsoft have a great section of their documentation which goes into this in more detail.

Regardless of which path you take though, the wiki provides you with a central place to communicate important information with your project team and external stakeholders. Powered by Markdown, it provides you with the ability to easily create, edit and share important information as well as provide collaborative editing functionality.

One of the most powerful features is the ability to insert Mermaid diagrams directly into your wiki pages without the need to create graphics. You can directly edit the Mermaid code in the wiki page, which when saved will be rendered.

Repository based Wikis

Personally, I prefer the control you get by creating your wiki in a repository, I find you get much more control over the content, you use a method which the team is already very familiar with in source control and a Git workflow that doesn't change all that much between code and documentation.

I think this provides a really tight consistent story for your projects and your teams, you can also of course make use of policies and pull requests for your documentation just like you would in repositories containing code, I also feel it allows you to add greater levels of automation to your documentation processes where possible.

For example, you can use automation to generate your documentation, make use of the .attachments folder which is used to store all your attachments and then commit straight to the appropriate branch, pull that back into master and then you have your updated documentation.

You can also use the .order file at the root of each folder to control the display order of the files in your wiki.

Take the above example, the default order other than Home is alphabetical, lets say we want Prerequisites above Installation, we can do this in our .order file.

You can see the .order file at the top of the repository above, either edit in your cloned directory locally, or edit in the browser. Simply enter the page names, line by line in the order you want and then commit the changes, you should have something which looks like below.

Now, back in your wiki, you should see your navigation menu has updated to reflect the changes we have just made.

Adding Mermaid diagrams

I talked briefly at the beginning of the post about the ability to add Mermaid diagrams into your documentation, let's look at how you define a simple flowchart declared using Mermaid, into your wiki.

The wiki supports adding flowcharts, sequence diagrams and Gantt charts. To add directly, you can use the following syntax:

::: mermaid

:::</pre>

First, we need to declare what direction we want the diagram to go, you can choose between top to bottom (TB), bottom to top (BT), right to left (RL), and left to right (LR).

Notice the two characters in brackets? This is the code we use to start the diagram. Let's make our diagram head left to right. Simply add the following syntax.

graph LR

Now lets add two basic boxes, labelled Start and Stop with an arrow between the two, you can do this with the following syntax on the next line.

Start --> Stop

Most flowcharts have decisions in as well, usually depicted by a rhombus shape. You can add one of those to your flowchart by editing the syntax as shown below.

A[Start] --> C{Decision}
C -->|Yes| D[Some Action]
C -->|No| E[Another Action]
D --> F[Stop]
E --> F

You will notice here I have assigned alphabetical notations to the shapes and added in notation such as curly braces and square brackets. The letters before the notations assigns the shape an ID, this can be used in other lines to define what happens to that box. Square brackets are used to define the text inside the shape and the curly braces define a rhombus shape. The text between the vertical pipes indicate the text that will be in the line connecting the box to another one. Here is how the diagram renders in the wiki once those changes are commited.

You can do many things with the syntax, such as change the styling of the boxes, for example, you can have round edges on your boxes by simply adding regular brackets around instead of square ones. If you were to do that, your syntax would look as follows.

A(Start) --> C{Decision}
C -->|Yes| D(Some Action)
C -->|No| E(Another Action)
D --> F(Stop)
E --> F

This is how this looks when viewing the diagram.

Of course, diagrams can get very complicated, the documentation for Mermaid is very good and gives you clear examples of how things are rendered. I highly recommend using it instead of generating images all the time.

Comments