Using Azure DevOps Wiki as Documentation Solution

This lab is a continuation of the How to create Work Breakdown Structure in Azure DevOps.

In this lab, we will leverage Azure Wiki and Markdown to create and manage documentation within Azure Wiki including:

1. Drafting structured and well-formatted documents using Markdown.
2. Generating more advance elements such as flow charts, Gantt charts, tables, and formulas to enhance documentation capabilities for technical projects.

This lab is tailored for professionals who may not have extensive coding knowledge but need to understand and be able to document.

Lab Introduction

We will try to recreate the Azure Markdown documentation page from Azure DevOps.

Exercise 0: Create the Azure DevOps Project

This exercise can be skipped if you did the Lab-1-Creating-Roadmaps. As projects has been created there as well.

Open Azure DevOps

• Navigate to https://dev.azure.com/<YourOrg> and sign in.

Create a New Project

• In the top-left corner, select the Azure DevOps logo to open the organization-level view.
• Click New project.
• In Project name, enter Azure-Migration
• In Description, enter DX has strategically decided to migrate all its workloads within the next two years. Currently, it maintains an on-premises data center with approximately 10,000 servers.
• In Visibility, make sure that Private is selected.
• Click on Advanced and set:
  • Version control to Git. (should be selected by default)
  • Work item process to Agile (should be selected by default)
• Click Create.

Exercise 1: Create the project wiki

Before diving into Markdown syntax, let’s start with a basic task to create a Wiki landing page. Don’t worry if you’re unfamiliar with Markdown. In the next exercises, I’ll guide you step by step through the details of Markdown syntax. For now, just follow these instructions to set up your landing page.

• Open https://dev.azure.com/<YourOrg>/Azure-Migration
• In the left-hand menu of your project, click Wiki
• Hit Create project wiki to open the editor for the home page.
• In the left-hand menu of your project, click Wiki (again). As you notice, you can not return to the original selection once clicked.
• Refresh the page.
• In the left-hand menu of your project, click on Summary and then click on Wiki. As I told you, there is no escape.
  • Project wiki in private projects
    • a project wiki does not expose the repository in Azure Repo avoiding backdoors to access the wiki
    • a project wiki allows you to set permission for the entire wiki, not particular pages.
    • Users with Stakeholders license have read-only permission for wiki pages and their revision. They do not have it for code wikis.
    • A project can have only 1 project wiki but many code wikis.
  • Once clicked, you cannot undo the creation procedure. You cannot publish additional code wiki until you complete it.
• Enter Azure-Migration as title in the input box on top. This will become the name of the page and kinda of the project wiki as well.
• Hit Save on the right top. Your screen should looks like this

• Let’s add some content into the page. Click on Edit
• On the left, you see the markdown editor and on the right the preview screen.
• Enter in the editor the following text# Use Markdown in Azure DevOps In this article, find basic syntax guidance for using Markdown in Azure DevOps features and wiki Markdown. You can use both common Markdown conventions and GitHub-flavored extensions. Use Markdown to add formatting, tables, images, and more to your project pages, README files, dashboards, pull requests, wikis, and so on. <br /> Not all Markdown syntax is supported across all features in Azure DevOps. The following table links to each basic syntax section in this article and highlights which features support it.
• We just added a h1 header in the page and few paragraph. Did you notice something? Before Not all Markdown, only 2 line breaks are added. Chance the code in as follow to have an extra line break.# Use Markdown in Azure DevOps In this article, find basic syntax guidance for using Markdown in Azure DevOps features and wiki Markdown. You can use both common Markdown conventions and GitHub-flavored extensions. Use Markdown to add formatting, tables, images, and more to your project pages, README files, dashboards, pull requests, wikis, and so on. <br /> Not all Markdown syntax is supported across all features in Azure DevOps. The following table links to each basic syntax section in this article and highlights which features support it.
• As you can see, markdown allows to add html tags to overcome certain conventions / limitations.

Exercise 2: Adding Horizontal lines, Headers and Emphasis

In this exercise, we will further add more basic formatting elements into the page.

• Let’s separate the first part from the second with a horizontal line and add a headings by adding the following code

***  ## Headings  # This is a H1 header  ## This is a H2 header   ### This is a H3 header   #### This is a H4 header   ##### This is a H5 header   ###### This is a H6 header

• As for the horizontal line, make sure the line above is blank.
• As you see, markdown supports up to h6, same goes for html. What if you need to mark a header as very important? Again, you would need to go with html. Replace the code above with the following

***  ## Headings  # This is a H1 header   ## This is a H2 header   ### This is a H3 header  <h3 style="color: red">This is a H3 header</h3>  #### This is a H4 header   ##### This is a H5 header   ###### This is a H6 header

Please mind that the editor only shows Header 1, Header 2 and Header 3 when you click on the first button of the control bar.

• What if you just wanna print a # like a hashtag #hellno. Add the following line at the end:

\#hellno

• Let’s continue with a few formatting options like bold, italic, italic and bold, ~~strike through~~, ~~bold itatic strike through text~~ by adding the following code

# Formatting options  Use _emphasis_ in comments to express **strong** opinions and point out ~~corrections~~  **_Bold, italicized text_**  ***~~Bold, strike-through text~~***  _**~~Bold, strike-through text~~**_

• There is no difference when using the underscore _ or the asterisk * for italic style. Both are valid, tools like Typora use * when using hotkeys whereas the editor in the Azure Wiki uses the underscore. Speaking of such, let’s add the following line below

Let's continue with a few formatting options like bold, italic, italic and bold by adding the following code

• Mark the first bold and press Ctrl + B on the keyboard
• Mark the first italic and press Ctrl + I on the keyboard
• Mark the first bold and italic and press Ctrl + B on the keyboard, then press Ctrl + I on the keyboard. You should get something like this as the result

Let's continue with a few formatting options like **bold**, _italic_, **_italic and bold_** text by adding the following code

• But what over <u>underlines</u>? Correct, we need to use html again.This is so <u>super</u> <ins>important</ins>.
• Please mind, that the use of <u> and <ins> is under disputed by some source, as html is in the transition to move to a content mark up language like <header>, <section>, <cite>, etc. instead of having tags, that mark styles like <b>, <i>, <u>, etc. So you could go for the recommended approach like<span style="text-decoration: underline;">This is so</span> <u>super</u> <ins>important</ins>. As for User Experience, the underline is not a good formatting option as it is easy to be confused with hyperlinks.
• Change the name of the page to Markdown-Introduction.
• Hit the option button next to Save and select Save with revision message to open the Save page dialog.
  • Open https://en.wikipedia.org/wiki/Richard_Stallman#Early_life
  • And copy the Early life of Richard Stallmann up to his Harvard study. (Hint: „Stallmann was born … on the IBM System/360“)
  • Paste this into the text area.
• Hit Save and Close afterwards.
• Hit the 3 dots on top right and select View revisions.
• You should see Stallman’s biography inside.

By the end, your page should looks like this:

The code for the entire page:

# Use Markdown in Azure DevOps In this article, find basic syntax guidance for using Markdown in Azure DevOps features and wiki Markdown.  You can use both common Markdown conventions and GitHub-flavored extensions.      Use Markdown to add formatting, tables, images, and more to your project pages, README files, dashboards, pull requests, wikis, and so on.      <br /> Not all Markdown syntax is supported across all features in Azure DevOps. The following table links to each basic syntax section in this article and highlights which features support it.       ***      ## Headings      # This is a H1 header ## This is a H2 header ### This is a H3 header      <h3 style="color: red">This is a H3 header</h3>      #### This is a H4 header ##### This is a H5 header ###### This is a H6 header      \#hellno      ***      ## Formatting options      Use _emphasis_ in comments to express **strong** opinions and point out ~~corrections~~   **_Bold, italicized text_**   ***~~Bold, strike-through text~~*** _**~~Bold, strike-through text~~**_      Let's continue with a few formatting options like **bold**, _italic_, **_italic and bold_** text by adding the following code.  <span style="text-decoration: underline;">This is so</span> <u>super</u> <ins>important</ins>.

Exercise 3: Adding blockquotes, code blocks, formulas and tables

Let’s proceed with adding a few more cool stuff in an sub-page:

• Move your cursor over the Markdown-Introduction page on the left. A triple dots should appears to the right of the page.
• Click the triple dot and hit add subpage
• Enter Working with Blocks as a title and respective the Header 1 element in the editor.
• Afterwards, let’s add a blockquote by adding

 > Single line quote >  > > Nested quote > >  > > > multiple line multiple line multiple line > > >  > > > > quote > > > >  > > > > > quote > > > > >  > > > > > > Heading > > > > > > ------- > > > > > >  > > > > > > **quote** ABC > > > > > >  > > > > > > > This is just an ordinary text _quote_ > > > > > > >  > > > > > > > > This is just an ordinary text _quote_ > > > > > > > >  > > > > > > > > > This is just an ordinary text _quote_ > > > > > > > > >  > > > > > > > > > > This is just an ordinary text _quote_

• As you may notice,
  • using the quote will add and left line and indent your text.The blockquotes can be nested as much as you like.Within the blockquotes, you can apply additional styles and elements like heading, formatting, etc. (event tables can be nested within blockquotes).

  | a | 1 | 1 |  | --- | --- | --- |  | b | 2 | 2 |  | c | 3 | 3 |  | d | 4 | 4 | 

• Let’s further proceed with code blocks by adding the following lin

```typescript  interface Disposable { dispose: () => void; }  ```

• You can also add codes within a line

The code block above creates a interface `Disposable` with a method `dispose`.

• Inline block do not have syntax highlighting meaning, it does not applies wonderful colors for different element type like variables, methods, etc.
• Beside code, the Wiki does support math formula. Same as for code it offers the inline option

Einstein said $e=mc^2$ in the past.

• And the block option

**The Cauchy-Schwarz Inequality**   $$  \left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)  $$

• Mind that the editor bar only offers the inline options for code and math formulas. Blockquotes is not listed.
• As we have seen above, tables are also supported. Add the following code below

| a  sdfsdfgdsfg | 1  sdfgsdfgdsfg | 1   sdfgdsfgdsfg  | |----------------|-----------------|-------------------| | b italic       | 2 asdfasdf      | 2 `incr()`        | | c  e=mc^2      | 3 italic        | 3 `counter()`     | | d  bold        | 4 underline     | 4  strike-through |

• Format the math formular within the table $e=mc^2$ as math formular
• Apply the formats within the table as written bold, <u>underline</u>, ~~strike-through~~ and <u>italic</u>
• Format the code within the table incr() and counter()
• Your table should look like this in the preview
  • 
• Mark the code for table and hit Ctrl + Shift + F on the keyboard to format the code.

  | a  sdfsdfgdsfg | 1  sdfgsdfgdsfg    | 1   sdfgdsfgdsfg      |   |----------------|--------------------|-----------------------|   | b _italic_     | 2 asdfasdf         | 2 `incr()`            |   | c  $e=mc^2$    | 3 _italic_         | `counter()`           |   | d  **bold**    | 4 <u>underline</u> | 4  ~~strike-through~~ |

• Instead of the hotkey, you could have click on the table icon (9th icon from the editor bar) and select Format Tables.
• But what about line break within a the table? (Bonus).
• Hit Save and Close

Your page should looks like this (including the bonus):

The entire code for this page

# Working with Blocks      ## Blockquotes > Single line quote >> Nested quote >>> multiple line     >>> multiple line     >>> multiple line     >>>> quote     >>>>> quote     >>>>>> ## Heading     >>>>>> **quote**     >>>>>> ABC     >>>>>>> This is just an ordinary text _quote_     >>>>>>>> This is just an ordinary text _quote_     >>>>>>>>> This is just an ordinary text _quote_     >>>>>>>>>> This is just an ordinary text _quote_                 >|a   |1   |1   |     >|----|----|----|     >|b   |2   |2   |     >|c   |3   |3   |     >|d   |4   |4   |           ## Code  ```typescript interface Disposable {         dispose: () => void;     } ```      The code block above creates a interface `Disposable` with a method `dispose`.      ## Math formulas Einstein said $e=mc^2$ in the past.      **The Cauchy-Schwarz Inequality**  $$ \left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right) $$       | a  sdfsdfgdsfg | 1  sdfgsdfgdsfg          | 1   sdfgdsfgdsfg      |  |----------------|--------------------------|-----------------------|  | b _italic_     | 2 asdfasdf<br/>so broken | 2 `incr()`            |  | c  $e=mc^2$    | 3 _italic_               | 3 `counter()`           |  | d  **bold**    | 4 <u>underline</u>       | 4  ~~strike-through~~ |

Exercise 4: Add Listing and ToDo-lists

• Let’s create a new subpage Open Points and add the following code to it

- [ ] A  - [ ] B  - [ ] C  - [x] A  - [x] B  - [x] C

• As you see, the preview will render a To Do list for you. Unfortunately, the Wiki does not support to check and uncheck the items without going into the Edit mode. This prevents stakeholders to make changes to the file.
• Further let’s add a numbered and unnumbered list into the page

1. First item.     - Item 1     - Item 2     - Item 3  1. Second item.     - Nested item 1        1. Further nested item 1        2. Further nested item 2        3. Further nested item 3           - Nested item 2           - Nested item 3

• Please mind, that
  • regardless of the number, the Wiki will numbered the list continuously. If you don’t want that, you would need to add an element in between such as <br/>
  • You can nest lists but you cannot create multi-level lists.

Exercise 5: Hyperlinks and Integration with Azure DevOps

One of the advantage to use Azure Wiki is its ability to access the information of the Azure DevOps Projects including the option to mention other users and groups, to embed query results, link to work items

• Let’s create a new subpage Linking and add the following code to add mention yourself in the page.

markdown @<your-name>

• Replace <your-name> with your name as shown in DevOps. You can click on your profile on the right top to check
• Now, let’s further add a link to an epic by adding the following code markdown #1
• Please notice, that the editor will automaticcally show a list to support you select the item
• The Wiki will show the status next to the epic.
• Azure Wiki even allows you to add an entire query inside the page. Append the following code to your file

markdown ::: query-table <query-id> :::

• The query must be stored as Shared Query.
• Please refer to Lab 2, Exercise 1, Task 1 "Create Queries" to create the query.
• As you can see. Even tree structure is supported in the view.

• Azure