How can Markdown help
Markdown is a lightweight markup language widely known and used for formatting text on the web and has gained a lot of traction in the technical documentation side of IT. Many of the “README” documents people find when downloading software are written in or inspired by Markdown. When speaking in purely test automation form it is used to make your test case easier to understand and organize within the framework.
Usually, when working with Azure DevOps, test case details would be added to the Test Case work item. However, there are some limitations from a development perspective such as versioning, history, and reverting. Git allows better tracking of history and easier processes to revert, while Azure DevOps work item history can only be inspected but not immediately restored to the previous version - manual work is required. Another important aspect from a development perspective is to have everything in one place, instead of going back and forth from IDE/Repos to Boards/Test Plans.
Lead by example
When used in separate files, Markdown can be used to create standalone documentation, such as project wikis, release notes, or user guides. These files can be stored within the source code repository alongside the code itself or hosted on a separate website or documentation platform. In this specific case, I use it for explaining what each test step does within a specific test case in order for anyone outside looking in to be able to visualize and understand my thought process behind creating the test itself.
Azure DevOps provides a built-in Markdown editor, which allows you to create and edit Markdown files directly within the Azure DevOps web interface. You can also use external Markdown editors, such as Visual Studio Code, to edit your files and then upload them to Azure DevOps.
In addition, Azure DevOps provides integration with other Markdown-based documentation systems, such as GitHub Pages and Docsify, which can help you publish and share your documentation. Overall, Markdown is a flexible and widely supported tool, and it can be a great choice for creating technical documentation within Azure DevOps.
How it looks and is constructed
Within the Markdown documentation, you can input the following:
Header: This is started with the “#” sign in the text. The size of the header can be adjusted up to 6 times. The more “#” You place before the header the smaller the text is.
Short description: Which is normally surrounded (but does not have to be with 2 asterisks on each side
A list of steps (items): Followed by a list of items or in this scenario test case steps explaining the thought process behind them.
Images: Links to images (that can follow steps that you may deem fit to contain an image) using the following format. The Alt text in the square brackets will be the name of the image and the image URL is pulled from a website or a link created by many of the screenshot programs available. I personally use ShareX.
URL Links: URL links are used if you would like to reference a website or possibly even add the one you automated the test in. It can also be used as a link to the repository in which the test was pushed such as Azure, Git, and so on.
Block quotes: To create a blockquote, add a “>” in front of a paragraph. You can even nest block quotes by adding an extra “>”.
A full list of syntax can be found here
Integration with Azure DevOps
As mentioned before Markdown is fully compatible and customizable with Azure DevOps. When you create a folder within the codebase you can link it with Azure DevOps to automatically list the document within the “Wiki” section of Azure DevOps.
To sync the Markdown documentation with Azure DevOps follow these steps:
- Go to your company's Azure DevOps website
- On the left-hand side hover or click on the option “Overview”
- Find the subsection “Wiki”
- On the dropdown, click the dropdown and select “Publish code as wiki”
- Once clicked a right-hand flyout will appear with the following fields to fill in
- Repository: This will be the repository that you are working on.
- Branch: The main branch in which you will merge the documentation
- Folder: Folder where the documentation is located in the codebase
- Wiki Name: Name of the wiki on Azure DevOps
- Once you are done filling everything out click the “Publish” button
Markdown is a simple yet powerful markup language that allows developers and testers to easily create well-structured and visually appealing documentation for their projects. With its simple syntax and support for rich formatting, including links, images, and tables, it has become a popular choice for documenting code, test cases, and project requirements. Also, with the seeming integration with Azure DevOps, Git, and others Markdown is practical for teams of all sizes.
