Working with your Azure Devops Wiki

How far have we come in terms of knowledge management today? The way we collaborate has changed significantly. Gone are the days when we only use email to share information. Was sharing knowledge in an email ever a thing? Maybe — I honestly cannot remember. Sharing knowledge in an email has a massive downside — the email gets lost in an Inbox. You can flag the email to get to it easily later — for sure. But it also means having to forward emails to parties not part of the original conversation. Email threads can be exhausting to say the least, especially when you are looking for one critical piece of information.

Another way of sharing knowledge is to have a central repository of say Word documents. People live and die by Word to this day — its perfectly fine. You can also share Excel files or any other file-based resource. Knowledge sharing using SharePoint where Microsoft Office files are hosted is also a great way to make information easily accessible to team members. Microsoft Office does come with a trade-off. Efficiently editing Office documents requires a licensed version of Microsoft Office. The editing capabilities of Word Online, for instance, does not feel quite as complete as the Word desktop application. Office works well with OneDrive — so you can easily edit documents knowing it will be updated. Documents can be easily shared from a OneDrive folder between team members using links. Its a great eco-system. But all too often I find Office documents to be too heavy from my developer-centric viewpoint. I barely use all the features for Word. The fact that you need a license for it will also lead me to favor lighter weight alternatives. Such as Markdown. I have probably mentioned Markdown so many times already you may think I’m a brand ambassador of sorts. Its not Markdown itself though — its the overall experience with it. As I may have stated already in previous posts Markdown is ubiquitous, especially in developer tooling. I’d pick Markdown documentation over Word 99.99/100 everyday. It makes knowledge sharing super easy. Finally I get to the point — Azure DevOps wikis use Markdown. Azure Devops also provides support for other formats such as Mermaid.

Azure Devops provides two flavors of Wikis. You can use the default project wiki bundled with it or alternatively you can point to a git repository within your project. I’m not sure if you can point to a GitHub repo — haven’t tried it. Pointing to a repository within your project is referred to as a “code wiki”.

Azure Devops Project Wiki

When creating a new project in Azure Devops a wiki is setup for you. In my brief experience so far the Azure Devops wiki is collaborative space for developers, business analysts and product owners. The Azure Devops wiki can be used to create and maintain specifications. Generally specifications are written by analysts. Again there is no general rule. You might find analysts prefer to write documentation in their browser whereas developers like myself prefer the VSCode option. The Azure Devops wiki provides a rich editing experience in the browser. Initially I thought the only way to maintain wiki documents was through the browser — boy was I wrong. The Azure Devops wiki can be cloned — its a git repository.

When you click on Clone Wiki a git repo URL is provided.

I love Visual Studio Code for editing and updating the wiki on my desktop. You can create commits for your edits which are then pushed to a remote branch.

As a sidenote — the Azure Devops wiki does not create folders in the conventional sense. The folders are Markdown files with index information. The files appear like folders in the Azure Devops wiki. I have, for instance, an Articles folder which I created in Visual Studio Code.

If you click on the Articles node above it displays a message.

If I then use Azure Devops to create sub-pages it appears in a folder structure, but isn’t quite a folder.

Sample Sub Page above is an editable page. If you inspect the structure in VSCode you will notice it creates a folder as well. But it also creates a Markdown document with a matching name. An “.order” file is also created.

Personally I prefer the folder structure without the matching Markdown file. It doesn’t bother me much if the folder cannot be viewed. If you have many team members editing the wiki the formatting of the file names can be unreadable if you use spaces, for instance.

When using Azure Devops you also get to use some Azure Devops-specific Markdown syntax. One example is the [[_TOC]] . It creates a table of contents at the top of the page.

I tried, unsuccessfully, to use the [[_TOC]] syntax on GitHub. I also added an extension to VSCode to visualize Azure Devops Wiki Markdown.

At this point I’m not sure what value a “code wiki” would add. Each team is different — maybe a code wiki has a different purpose to a project wiki.

Azure Devops Code Wiki

In addition to having a project wiki you can also have a “code wiki”. Its fairly straightforward to setup. Select “Publish code as wiki”.

The Code Wiki inherits the same editing experience as the Project Wiki. You could potentially have multiple code wikis. Maybe a Project Wiki can act as a space for all your specifications. Code wikis could be used as documentation generation space? Its not too clear at this stage. It depends on the size and needs of your team I guess.

Conclusion

Wikis are awesome for collaboration. They also do not suit every individual’s style — I am willing to bet there are people who prefer Word documents. Personally I find using Wikis a great way to narratively expand on ideas. I find myself dealing with complexity best when I can use a wiki page to scribble some ideas. Wikis make it easy to embed code. Sometimes you need to bridge the gap between the customer needs and the technical aspects. I find wikis are great for such a purpose. You can easily extract a piece of code into a wiki page for analysis. Reading code to understand its meaning and intent is as valuable if not more so than writing code.