[AzureDevops] 初探 Wiki 文件管理

前言
隨著團隊成員越來越多，在人員越來越多發現有些基本知識像是 Code Review 規範或是新人報到流程沒有系統化整理起來，因此需要一個知識管理平台存放相關 Domain 與流程相關文件，於是開始 suvery 知識管理平台發現在 Azure Devops Wiki 符合好管理、版控紀錄、可以使用 markdown 方式撰寫十分方便，可以做為團隊上 KM (knowledge management) 文件中心，這篇文章就來簡單介紹小小的使用心得。

建立 Wiki Project
首先在 Azure Devops 建立完 Demo Team Knowledge Management 專案，接著建立 wiki 專案，到左邊點擊 create project wiki

接著會請你建立第一個 wiki page，在這編輯視窗是可以透過 Markdown 格式輸入你整理好的資訊文件內容，接著就完成了第一頁 wiki page。

關閉 Azure Devops Service
建立完專案後，如果專案目的是專門給 Knowkedge Management 文件管理使用的話，可以考慮關閉專案中其他 Azure Devops Service 像是 Board、Pipeline、Test Plans 等服務，選單就會比較乾淨些。關閉方式可以透過到 Project setting > Azure Devops Service > Off service

關閉之後，在 Project 左方選單就僅會呈現必需的資訊 (非必要，視主管與團隊需求而定)

設定 Access level
建立完專案後，必須在設定用戶權限才可以具有訪問專案的權限，如果沒有特別設定的情況下預計權限會是 Stakeholder，可以訪問到的功能是 Azure Boards 和 Azure Pipelines 部分功能；要讓團隊成員可以編輯則要將訪問權限設定為 Basic，就可以讀取大部分的 Azure Devops 服務，詳細訪問級別權限與讀取服務可以參考 About access levels

Clone Wiki
在編輯上有兩種方式，你可以選擇直接在 Azure Devops 上直接透過畫面編輯，或是把專案直接 Clone 下來 (背後也是 Git Repo)，Clone 功能可以透過專案點擊右邊會跳出 more action，接著選擇 Clone wiki 複製 Git repo 位置，再透過你熟悉的工具進行編輯的動作

Wiki Page
新增 page
可以透過下方的 new page 進行新增 wiki page 的動作，如果新增完頁面後想要新增子頁面也可以透過 add sub-page 動作新增，在 page title 部分是有限制的，wiki page 名字是不能重複(唯一性)，不能與其他已存在的 wiki page name 重複；另外在 page title 上如果輸入空白的話系統預設會用 - 來取代。

如果要進行頁面的排序調整，可以透過滑鼠拖拉的方式在 Azure Devops 介面直接調整；若是使用 Git repo 則可以開啟 .order 檔案透過手動修改排序方式達到你要調整的排序。

Page 編輯

在編輯文字內容上是使用 Markdown 風格，關於 markdown 基本語法詳細說明可以參考微軟官方文件 Syntax guidance for basic Markdown usage，這裡就不在多加說明，這裡我就列出個人覺得實用的幾個功能
Table of content (TOC)
當你的內容需要標題時可以在指定位置插入 TOC，讓在閱讀時可以透過導引快速定位你要找的資訊內容，對於文件內容過長時很好用

Insert Mermaid diagram
如果文件中需要說明模組之間的互動關係，或是畫流程圖時，可能在過去都是透過軟體繪製，像是之前在部落格介紹過的 PlantUML - 在 Visual Studio Code 繪製 UML 圖，再將畫完的結果截圖貼在文件內容中。使用 Mermaid 則可以替你省下這些工作

舉例來說上述內容簡單描述 User 發送請求，透過應用程式讀取資料庫的流程，在 Mermaid 使用下列語法描述

::: mermaid
 graph LR;
 A[User] --> B[Application] --> C[Database]
:::

可以在編輯視窗中劃出所需要的流程圖，可以說是相當的方便。目前內建支援三種圖形分別是循序圖、流程圖與甘特圖，如果想了解更多細節內容可以參考官方文件 add-mermaid-diagrams-to-a-wiki-page 說明。

感想
工欲善其事，必先利其器。在過去開發或是接觸到不同的專案時，最讓人害怕的就是沒有文件說明要重新摸索，可能會花費較長的時間來整理前人留下來的祖產內容，但部分開發人員對於撰寫文件也是不熟悉的，如果可以讓撰寫文件這件事變得容易上手，就有機會達到這兩者之間的平衡。若是你的團隊也有類似的困擾時不妨可以參考 Azure Devops Wiki 的服務，讓知識文件化對團隊夥伴帶來幫助，hope it help :D

參考
Add and edit wiki pages
Syntax guidance for Markdown usage in Wiki