
Azure DevOps Wiki Code Block can be customized to suit your team's needs, with options to add a title, description, and even a call to action to guide users.
You can also categorize your code blocks to make them easier to find and use. This helps keep your wiki organized and reduces clutter.
To further streamline your wiki, consider using pre-existing code blocks, such as the ones provided by Azure DevOps. These blocks are designed to save you time and effort, and can be easily inserted into your wiki.
By leveraging these features, you can create a more efficient and user-friendly wiki that boosts productivity and collaboration among team members.
Intriguing read: Download Azure Wiki Files
Azure DevOps Project
Creating an Azure DevOps project comes with a built-in wiki that's a collaborative space for developers, business analysts, and product owners.
The Azure DevOps wiki can be used to create and maintain specifications, which are often written by analysts, but there's no hard rule about who does what.
You might enjoy: Azure Devops Wiki
As a developer, I've found that the wiki provides a rich editing experience in the browser, but I prefer using Visual Studio Code for editing and updating the wiki on my desktop.
You can create commits for your edits in Visual Studio Code, which are then pushed to a remote branch.
The Azure DevOps wiki does not create folders in the conventional sense; instead, folders are Markdown files with index information.
If you create a folder in Visual Studio Code, it will appear as a folder in the Azure DevOps wiki, but without the conventional folder structure.
Creating sub-pages in the Azure DevOps wiki generates a Markdown document with a matching name and an ".order" file, which can be a bit confusing if you have many team members editing the wiki.
Personally, I prefer the folder structure without the matching Markdown file, especially when working with team members who use spaces in file names.
Wiki Documentation
Wiki documentation is a crucial aspect of Azure DevOps, allowing teams to create and manage knowledge bases, track progress, and share information. You can create Markdown deployment documents and publishing scripts to automate this process.
To get started, you'll need to create a PowerShell script, such as Create-DeploymentDocument.ps1, which can be used to generate the ARM Template Markdown document and publish it to the Azure DevOps wiki.
Azure DevOps wiki pages can be created dynamically from within a pipeline, as shown in the Creating Azure DevOps WIKI Pages from within a pipeline - part 1 resource.
Using HTML Tags in Wiki Pages
Using HTML tags in wiki pages is a great way to add some extra flair to your documentation. You can create rich content using HTML tags.
In wiki pages, you can nest Markdown within your HTML, but you must include a blank line between the HTML element and the markdown. This is a good thing to keep in mind when crafting your wiki content.
Pasting rich content as HTML is supported in Azure DevOps Server 2019.1 and later versions, so if you're using an older version, you might not be able to take advantage of this feature.
Related reading: Using Vscode for Azure Devops
Create Markdown Deployment Document and Publishing Script
Creating a Markdown deployment document and publishing script is a crucial step in maintaining up-to-date wiki documentation.
You can create a single script that combines the tasks of creating an ARM Template Markdown document and publishing the document to the Azure DevOps wiki.
The script is called Create-DeploymentDocument.ps1.
Yaml Pipeline
The Yaml pipeline is a crucial component in Azure DevOps, allowing you to execute multiple steps with ease.
To create a Yaml pipeline, you need to define the steps you want to execute, such as the one mentioned in the example. The yaml pipeline to execute above steps should look like this:
This pipeline definition will run the specified steps in the order they are listed, making it easy to automate complex workflows.
Create Deployment Document and Publishing Script
Creating a deployment document and publishing script is a crucial step in managing your Azure DevOps wiki code block.
You can put everything together in one script to create the ARM Template Markdown document and publish the document to the Azure DevOps wiki. The code for this can be found in the "Create-DeploymentDocument.ps1" script.
The script combines all the necessary steps into a single, efficient process. This makes it easier to manage your wiki code block and keep your documentation up to date.
This script is a great example of how to automate tasks and streamline your workflow in Azure DevOps.
For more insights, see: Nextjs Code Block
Motivation and Scenario
Teams with good documentation deliver software faster and more reliably than those with poor documentation, according to the Accelerate State of DevOps Report by Google in 2021.
Maintaining consistent and up-to-date architecture documentation can be a challenging and time-consuming task, especially in fast-changing environments with inadequate tooling.
The goal is to have a similar Wiki document created for each of the Azure Resource Deployments being made via an Azure DevOps Pipeline, as demonstrated by creating a Wiki page for an Azure Logic App deployment.
Motivation for Using Azure DevOps
Using Azure DevOps can significantly accelerate software delivery and improve reliability. Teams with good documentation deliver software faster and more reliably than those with poor documentation, according to the Accelerate State of DevOps Report, Google 2021.
Maintaining consistent and up-to-date architecture documentation is a challenging task, especially in self-organized development teams. Disruptive workflows, missing automation, and versioning issues are common problems encountered.
Teams can create their architecture documentation using their IDE, combining open-source tools to generate documentation from code. This approach aims to simplify the process and make it more efficient.
Azure DevOps can help automate the process of generating architecture documents and publishing them to GitHub Pages and Confluence via GitHub Actions. This automated process can save time and reduce the risk of inconsistent and outdated documentation.
Here's an interesting read: Link Azure Devops to Github
Scenario for Azure DevOps Implementation
The goal of this Azure DevOps implementation is to create documentation for each Azure Resource Deployment made via a Pipeline.
The scenario involves creating a Wiki page for each deployment, as demonstrated with an Azure Logic App deployment.
In this context, a Wiki page is created to document the deployment, similar to the one shown for the Azure Logic App deployment.
The end result is a well-documented record of each Azure Resource Deployment made via the Pipeline.
The Pipeline is designed to automate the creation of these Wiki pages for each deployment, making it easier to track and manage changes.
Discover more: Azure Devops App
Task Management
Task Management is a breeze with Azure DevOps wiki code blocks. You can use lightweight task lists to track progress on your to-dos.
Lightweight task lists are great ways to track progress on your to-dos as a pull request creator or reviewer in the PR description or in a wiki page. Select the Markdown toolbar to get started or apply the format to the selected text.
Work Items Link
Linking work items from a wiki page is a breeze. Simply enter the pound sign (#), and then enter a work item ID.
This method allows you to quickly connect relevant information and streamline your workflow.
Sources
- https://learn.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance
- https://medium.com/@fredrik_erasmus/working-with-your-azure-devops-wiki-ce55a79b6631
- https://devops.stackexchange.com/questions/17276/can-you-include-an-azure-devops-wiki-inside-an-existing-repository
- https://stefanstranger.github.io/2020/04/25/CreatingAzureDevOpsWIKIPagesFromWithApipelinePart2/
- https://www.codecentric.de/wissens-hub/blog/architecture-documentation-docs-as-code-structurizr-asciidoctor
Featured Images: pexels.com