Documentation: wikis, Markdown and Mermaid, release notes, docs from the Git history

At Nordlicht Reisen GmbH, a fictional travel agency, knowledge lives in people's heads. Whoever is sick takes the knowledge about how the booking portal is delivered along with them. The new colleague asks how a version comes into being and gets three different answers. In addition, sales wants to know what the new version brings, and the partners need a description of the interface. Your task: make sure documentation lives where the code lives, results from the work flow and does not have to be updated by hand.

These are the skills of the exam: wikis and process diagrams (Markdown, Mermaid), documentation for releases and APIs and documentation from the Git history.

Prior knowledge: Pull requests, issues and traceability are in lesson 1.1, Boards and GitHub in lesson 1.2. For Markdown and Git, the course assumes basic knowledge. K3 teaches versions and feeds in lesson 3.7.4; versioning as a strategy is in lesson 3.2.

Note: All statements come from the documentation of Microsoft Learn, GitHub and Git; the pages are listed under "Further reading". The commands, files and menu paths of this lesson were not run; they come from the reference of Microsoft and GitHub.

Wikis

Azure DevOps: one wiki per project, backed by Git

According to Microsoft's page "Create a wiki for your project", in Azure DevOps every project has a wiki, and a Git repository backs it. When you create a project, the repository does not exist yet; you create it, or you publish existing Markdown files from a repository. Anyone with access to the project can view the wiki, stakeholders too. To edit it, you must be a member of the Contributors group, with at least Basic access.

There are two kinds, according to the page "Provisioned wiki vs. published as code wiki":

The folder structure is the same for both: The repository of a project wiki is named <project name>.wiki, its main branch wikiMain. It contains one file per Markdown page at the top level, a file .order in every folder (it sets the order; what is missing there ends up at the end of the list), one folder per page with subpages, and the folder .attachments for attachments. A page with subpages needs a Markdown file and a folder with the same name in the same folder. On the branch wikiMain, you can set up policies as with other branches.

Publishing as code works in the browser (Wiki, Publish code as wiki: choose repository, branch and folder, assign a name, Publish) or with the Azure CLI:

az devops wiki create --name "Portal-Doku" --type codewiki --repository nordlicht-portal --mapped-path /docs --version main

For az devops wiki create, the reference names, among others, --name, --type (projectwiki or codewiki), --repository, --mapped-path (the page lists it as the "mapped path" of the wiki; / publishes from the root), --version (the branch) as well as --org and --project. The head of the branch is assigned to the published wiki; changes to the branch appear in the wiki without any further procedure. According to Microsoft, you can publish up to 10 branches per published code wiki. The advantage: documentation follows the pull request flow of the code, but gets a table of contents, hierarchy, versions and a search.

Further notes: A table of contents is set with [[_TOC_]] (according to Microsoft's notes on Azure DevOps Server 2019); you drag attachments into the editor and they land in .attachments; anchors jump to headings (lowercase heading with hyphens). For work items, # with a number is enough, for people @.

GitHub: one wiki per repository

According to GitHub's page "About wikis", every repository has a Wiki area for long-form content about the project. By default, only people with write access may change the wiki; for public repositories, you can allow anyone on GitHub.com to contribute. Wikis of private repositories are visible only to people with access to the repository. There is a soft limit of 5,000 files. You write in Markdown (or another supported format), and GitHub renders formulas, diagrams, maps and 3D models. Whether the wiki itself is a Git repository is not stated on this page.

Where does which documentation go?