How-to Edit, Review, and Approve Markdown Files

This guide describes how to use Markdown to document technical information using the Azure DevOps (ADO) wiki. The Markdown files can be reviewed, approved, and baselined with the code. The code and technical documentation can be restored from the same baseline when a released product needs to be updated.

ADO is a Microsoft platform that helps teams collaborate on software projects, covering version control, project tracking, testing, and deployment. For technical writers using Markdown, the most relevant aspect is Azure Repos, which supports Git for version control. Writers can store and manage Markdown files in Git repositories, track changes, and collaborate using pull requests and branch management. This ensures documentation stays organized and versioned properly.

Intended for

• Anyone providing information in Markdown that needs review & approval in ADO, e.g.,
  • A software engineer who creates the design.
  • An architect describing the architecture using PlantUML or Mermaid.
  • A quality engineer who describes processes and guidelines.
  • A product owner who writes user documentation.
  • A process owner who writes process documentation
  • A technical writer who manages user manuals

Overview

Activities

Create repo

To create, review, and approve Markdown files, store the files in a ADO repository (repo). The repo enables branching, merging, commits, and pull requests. First, create the repository in your ADO project with at least one Markdown file.

See Microsoft for information: Publish a Git repository to a wiki.

Create new branch from master

Create a new branch from the master branch before you make any updates. With a branch, you can make multiple changes to the Markdown files and keep them organized. The master branch remains unaffected until you merge the changes to the master with a pull request.

Ensure you are on the ADO "Edit in Repo" page, not the wiki page. Locate the branch symbol () on the page, select it, and create a new branch.

See Microsoft for information: Create a new Git branch.

View, edit, and commit Markdown files

Edit using ADO wiki

View the Markdown files in the ADO wiki using a web browser. Navigate to the ADO project where the repo and wiki reside. To access the ADO wiki and edit the Markdown files, you need a license and access to the ADO project.

In the wiki, you first need to publish the branch you created earlier by selecting "Publish code as wiki" from the top menu in the navigation window. This step only needs to be performed once per branch.

Make sure you select the branch you want to work in. Typically, the master branch is the default branch and is write-protected. If you try to change the master branch, you can edit it, but not save the changes.

Navigate to the page you want to change, click the "Edit" button, and make changes. Then, use the "Save" button on the wiki to store the changes. ADO will suggest a standard message for the change. You should modify the standard message to provide a more precise explanation of the changes made.

See Microsoft for information: Add and edit wiki pages.

Edit using repo

Markdown files can also be edited directly in the repo using a browser. Open the repo in ADO and find the branch you want to make the changes in. Navigate to the file in the repo. The contents of the Markdown file will be shown in the browser. Select "Edit" and make the desired changes to the Markdown file. When completed, use the "Commit" button to save the changes.

You can enter a message with the "Commit" to explain the changes you made to the file. The changes will be added to the commit history, which can help you understand what changes have been made to the Markdown file.

Spell and grammar checks

Ensure the spelling and grammar are correct before creating the pull request.

Create a pull request and review

Once you are satisfied with the Markdown file changes, you can create a pull request to merge them from your working branch into the master branch.

1. The author initiates a pull request.

   • Title – one sentence highlighting the changes made.

   • In the description, define the review type:

     • [Full]: Full document.
     • [Focused]: Only changes made since the last version (minor).

   • In the description, highlight the main changes, including the reasons for them (which are more elaborated on than in the title).

   • In the description, include review roles and names according to the RACI model (see the artifact list for the relevant process). Refer to the artifact list on the Quality & KPI page for process-related artifacts.

     • Name, role (R)
     • Name, role (A)
     • Name, role (C)
     • Name, role (I)
     
     

     Note: Add “A/C” roles to “required reviewers”, and add "I" roles to “optional reviewers”. In the pull request description, set a time limit for the review.

2. The reviewer reviews the work product.

   • Review the work product according to the designated review type.
   • Add comments and suggestions:
     • If the reviewer identifies a major issue within the commit, they should set “Waiting for author” in the pull request to prevent the merge until the issue is resolved.
     • If the reviewer identifies a minor issue within the commit (e.g., a spelling error or inconsistent naming conventions), they should set “Approved with suggestions” in the pull request.
     • If the reviewer identifies an issue to be best resolved through a review meeting, indicate this in the comment.
   • In case of a review meeting, the decisions shall be documented in the pull request.
     The reviewer checks whether modifications have been made in response to later review comments.
     It is recommended that the author inform reviewers of any larger, late modifications.

3. The author responds to comments.

   • The author responds to comments (either continuously or after all comments have been entered) with no action (and an explanation) or by making relevant changes.
   • The author sets the comment to resolved.

4. Reviewer “waiting for author”.

   • Reviewers with the status “waiting for author” control resolved comments and either approve the pull request or add a new comment.

5. Approver completes review. (Safety)

   • The approver is responsible for checking for:
     • The stipulated time frame has ended.
     • All comments are resolved.
     • All relevant review roles, according to RACI, have been invited and approved the commit.
   • When it is ok to close, it shall be added as a comment.

6. The author completes the pull request.

   • When the approver has commented "ok to close", the pull request can be completed.
   • The author completes the pull request by merging it into the Master branch.

7. Merge Conflict

   • If a merge conflict occurs, the author shall contact the impacted author and resolve the conflict.
   • If significant changes are required, request a re-review.

See the video on Pull requests in ADO, and the guidance on Resolve merge conflicts.

Details

Renaming Markdown files

To rename a file while preserving its version history, use the git mv command. If you rename a file using other methods, such as in an ADO repo, the old file is deleted, and a new file is created with the new name, resulting in the loss of the version history. Loss of version history also occurs if you move a file from one folder to another without using git mv.

It is possible to get the version history from a renamed file as follows:

1. Clone the repo locally on your computer.
2. Find the full path to the renamed file, including its previous path and name.
3. Run the command git log -- <path to file> in the terminal.

Compare versions in ADO

You can see the changes made to earlier versions of the wiki. Select "Edit in Repos" from the wiki page and then choose the "Compare" tab.

With this function, you don't need to add a manual table with changes at the end of the Markdown file. ADO automatically takes care of it. You can also see who made the changes in the "Blame" tab.

See Microsoft for information: View wiki page revision history

Q&A

I'm new to ADO - how do I learn to work with Markdown?

Writing in Markdown is simple. Refer to the Markdown Guide for guidance.

Why use Markdown instead of Microsoft Word?

Using Markdown files, you can document and write code simultaneously. For example, when you change a code section, you can update the architecture or design using Markdown. You can manage both the code and documentation with the same pull request. And there is no need to switch to another tool or document management system to work with technical documentation.

The technical documentation and the code can also be baselined with a release. This makes it simpler to revert to a baseline (release) and update the technical documentation and code at revisions or roll-ups.

Are other companies working with Markdown?

Microsoft utilizes Markdown to document the technical aspects of tools, APIs, and other resources. They have extensive documentation sites, often used for open-source applications (e.g., VS Code, ADO).

Are there any other recommended Markdown tools?

There are many tools available for editing Markdown files. The web browser is sufficient if you write simple text and edit the Markdown in ADO. However, you may need a better tool to integrate pictures, diagrams, and drawings.

Tool name	Level	Comment
ADO wiki	Beginner	A good alternative for updating the Markdown files in your web browser is the ADO wiki. You can do most updates with the ADO wiki.
Typora	Beginner	Good editing capabilities. Both editing and viewing are in the same window. You can download and install the application on your PC. However, it lacks integration with Git (ADO), requiring files to be downloaded and uploaded manually to ADO.
Writage	Beginner	A plugin for Microsoft Word enables you to create and edit Markdown files (with the .md extension) in a visual interface. It can also save your .docx files in plain text format with Markdown markup.
Visual Studio Code	Advanced	An excellent alternative for editing Markdown and graphics, it is free to install and use, and is integrated with Git/ADO. Can handle merging, branching, commits, and pull requests. It has many plugins to improve editing capabilities. Recommended plugins: "Draw.io integration", "Grammarly", "PlantUML", "Spell Right", "SVG viewer", "Markdownlint"
Visual Studio	Advanced	The best tool for engineers and testers already working with Visual Studio. They do not need to switch to another tool (such as MS Word or SharePoint), and it is possible to update both the Markdown and the code with the same commit, i.e., update the code and documentation simultaneously.

References

• Microsoft: Create a wiki for your project
• Microsoft: Publish a Git repository to a wiki
• Microsoft: View wiki page revision history
• YouTube: Markdown Crash Course