Overview

In this lab, you’ll learn about the wiki feature of Azure DevOps that enables easier collaboration experiences for development teams. Each project in Azure DevOps now supports its own wiki, which enables you to conveniently write pages that help your team members and other users understand, use, and contribute to your project.

Prerequisites

• None

Exercise 1: Wiki collaboration with Azure DevOps

Task 1: Creating and editing a project wiki

1. Create a new team project on Azure DevOps.

2. Use the navigation to get to the Wiki hub.

   

3. Since this project does not yet have its wiki configured, click Create project wiki to set one up. When you create your first wiki, Azure DevOps will provision a git repository that will store all your pages and artifacts.

   

4. Enter “Home” as the title of the first wiki page. Enter some body content, such as “Welcome to our project!”. Azure DevOps wikis support Markdown, and you can learn more here. Click Save.

   

5. Click Close to exit the edit experience.

   

6. Your first wiki page is now available for everyone to see.

   

7. By default, all members of the Contributors group can edit README files and wiki pages. Stakeholders can read files and revisions, but cannot edit anything. From the More ellipsis menu, select Wiki security to review permissions.

   

8. Since the wiki is stored as a Git repo, the permissions are set against the repo and passed through the user experience. Close the dialog when satisfied.

   

9. Locate the Pages panel on the left side of the view. It lists all of your wiki pages, which is just the one at this time. You can easily add and manage pages here. From the dropdown menu for the Home page, select Add sub-page.

   

10. Set the title of this new page to “Getting started” and type some body content.

    

11. This time, select the Save | Save with revision message to specify a comment.

    

12. Enter “Added stub for instructions” and click Save.

    

13. Close the editor view.

    

14. Now add a sub-page to the Getting started page.

    

15. Set the title for this page to be “Development environment”. Add a list of system requirements that includes Windows Server 2016, Team Foundation Server 2018, and Visual Studio 2017 using the markdown list format as shown below. Click Save and then Close the edit view.

    

16. Click Edit to make a quick update.

    

17. Change the reference from TFS 2018 to Azure DevOps.

    

18. Use the Save | Save with revision message dropdown to provide a more descriptive commit message.

    

19. Enter a message explaining the change and click Save. Then Close the edit view.

    

20. From the ellipsis dropdown, select View revisions to see a list of changes committed for this page.

    

21. Click the most recent revision.

    

22. Azure DevOps provides a diff view so that you can easily see what was changed. You also have the option to revert to this version with a single button click.

    

23. Return to this wiki’s home using the breadcrumb navigation at the top.

    

24. You can easily rearrange the order of the pages using the tree view on the right. Drag the Getting started page slightly up until a green line appears under the Home page. This indicates that you want to make these pages peers.

    

25. Since the page is being re-parented, you’ll need to confirm the move. This kind of move will break links you will have manually added to other pages (none at this point), so you’ll need to decide how you will want to deal with them. In this case there are no links, so click Move.

    

26. Sometimes wikis can get pretty big, so it’s important to be able to find specific pages. Type “env” to filter the pages down to just those whose titles include that text.

    

27. Wiki pages are also indexed to show up in search results. Use the search bar in the top right corner to search for “Azure”.

    

28. The wiki page you just updated should appear as one of the results. Click it.

    

29. Now anyone working on the project can easily find wiki content alongside code and work item results.

    

Task 2: Publishing code as wiki

1. Content that you already maintain in a Git repository can be published to a wiki. For example, content written to support a software development kit (SDK), product documentation, or README files can quickly be published to a wiki. Multiple wikis can be published within a single team project. To get started, navigate to the Repos hub.

   

2. Create a New repository.

   

3. Set the new Repository name to “Docs” and check the Add a README option. Click Create.

   

4. From the README.md dropdown, select Rename. We will reuse this file for the wiki itself.

   

5. Change the name to “Our-team.md”. Note that the wiki engine will use the name of the file as a title of the article and automatically replaces dashes with spaces. Click Commit.

   

6. From the Our-team.md dropdown. Select Edit.

   

7. Optionally modify the default markdown in the file and Commit the changes. Confirm the commit when prompted.

   

8. Now that we have a file in place, let’s publish our code as wiki. From the Overview navigation, right-click Wiki and select Open in new tab. The next few steps will involve making changes and reviewing the results, so it will be easier to have a browser tab open to each.

   

9. From the wiki dropdown, select Publish code as wiki. Note that this dropdown will enable you to unpublish a wiki later on.

   

10. Ensure Docs is the selected wiki. Note that you also have the option to select a specific branch if you prefer. In this case, leave it to master. Click the Browse button to select a Folder.

    

11. Select the root of the repo and click OK.

    

12. Set the Wiki name to “Documentation” and click Publish.

    

13. You should now see the markdown file you edited earlier as the landing page of the wiki.

    

14. Note that you can also publish different versions of a wiki.

    

Task 3: Editing wiki in a repo

1. You can edit the repo however you like, whether it’s using Visual Studio or any other Git-compatible tools. You can also continue to edit the wiki in the browser, which we will do in this lab. Return to the tab open to the wiki repo.

2. From the dropdown for the Docs repo root, select New | Folder.

   

3. Enter a New folder name of “Upcoming-events” and a New file name of “January-events.md”. Note that the same naming convention is used for folders. Click Create.

   

4. Add some markdown to the January events page and Commit the changes. Confirm the commit.

   

5. Return to the tab open to the wiki browser and refresh the page.

6. There is now a folder for “Upcoming events” and a page for “January events”.

   

7. Return to the tab open to the wiki repo.

8. From the Upcoming-events dropdown, select New | File.

   

9. Name this file February-events.md and click Create.

   

10. Add some markdown to the February events page and Commit the changes. Confirm the commit.

    

11. Return to the tab open to the wiki browser and refresh the page.

12. Note that the pages are orders alphabetically by default. If you would like to set a specific order, you may do so using a .order file.

    

13. Return to the tab open to the wiki repo.

14. Add a new file to the Upcoming-events folder as before.

    

15. Name this file “.order” and click Create.

    

16. Put the names of the files without their extensions in the order you want them to be displayed. In this case, put January-events before February-events. Commit the file and confirm.

    

17. Return to the browser tab with the wiki viewer and refresh the page. The articles will now be ordered as defined in the .order file.