tech docs

gov.uk一個登錄技術文檔

該倉庫包含文檔，以幫助政府部門的船上登錄名的技術人員。它是使用技術文檔模板發布的。

改變內容

Gov.uk One登錄技術寫作團隊擁有此文檔，並負責批准內容更改。它寫為以用戶為中心並符合GDS內容標準，這意味著以下內容：

• Gov.uk計劃，寫作和管理內容指南
• gov.uk樣式指南
• gov.uk技術風格指南
• 其他明確的寫作原則

如果您在gov.uk One登錄名上工作，則應聯繫技術寫作團隊以進行幫助，除非內容更改並且不影響用戶行為。

小型內容更改包括：

• 添加澄清以提高理解
• 糾正代碼樣本
• 修復斷鍊路或錯別字

您可以自己進行這些更改，然後請求有關拉的請求的技術作家評論。如果您不確定更改是否很小，請在我們的＃DI-Technical-writing Slack頻道上與我們聯繫。

進行技術更改

編排團隊負責技術文檔平台的維護和運營健康。您應該諮詢他們以批准該領域的任何變化。

示例包括：

• 更改github動作工作流程
• 更改AWS部署或建立基礎架構
• 依賴項更新
• 不更改內容的紅寶石更新

預覽您的文檔更改

要在瀏覽器中預覽您對文檔中的任何更改和添加，請克隆此存儲庫，然後在此存儲庫中使用Dockerfile在計算機上運行中間人服務器，而無需在本地設置Ruby。

此設置已啟用了實時重新加載，這意味著您的更改將在您在源目錄中編輯文件時應用。唯一的例外是，如果您更改config/tech-docs.yml ，則必須停止並重新啟動服務器以查看預覽中的更改。您可以使用Ctrl-C停止服務器。

運行助手腳本：

./preview-with-docker.sh

構建Docker容器可能需要幾分鐘，特別是如果您是您第一次運行腳本。當服務器完成加載後，您應該在終端中查看以下輸出：

== View your site at " http://localhost:4567 " , " http://127.0.0.1:4567 "
== Inspect your site configuration at " http://localhost:4567/__middleman " , " http://127.0.0.1:4567/__middleman " /usr/local/bundle/gems/tilt-2.0.11/lib/tilt/redcarpet.

更改圖表

圖是滿足的，因此一旦您進行了更改，就應該要求技術寫作團隊進行審查。

您可以通過安裝和使用draw.io桌面應用程序在source/images/originals文件夾中編輯draw.io文件。

每個圖使用一個draw.io文件。

安裝draw.io桌面應用

運行以下命令從命令行使用draw.io桌面應用程序。

 brew install --cask drawio
alias draw.io='/Applications/draw.io.app/Contents/MacOS/draw.io'

編輯和發布圖表

請按照以下步驟：

1. 使用draw.io創建並修改圖表。
2. 將draw.io文件保存到source/images/originals文件夾中。
3. 將圖作為可擴展的向量圖形（SVG）發布。
4. 將SVG文件保存到source/images文件夾。

有用的命令

更新圖表：

 draw.io source/images/originals/top-level-technical-diagram.drawio

生成圖表的SVG版本，並將其保存到source/images/originals夾中：

 draw.io -x -o source/images/top-level-technical-diagram.svg source/images/originals/top-level-technical-diagram.drawio

draw.io -x -o source/images/technical-flow-diagram.svg source/images/originals/technical-flow-diagram.drawio

linting gov.uk一個登錄技術文檔

該存儲庫使用Vale和GDS Tech Docs Linter Ruleset。

在本地機器上安裝襯裡

您需要：

• 安裝自製
• 安裝谷

用您的代碼編輯器覆蓋

許多代碼編輯器為谷提供擴展名或插件，在您更新文檔時可能會引起錯誤。您仍然需要在本地計算機上安裝谷。

用vale命令行接口（CLI）覆蓋

默認情況下，必須從與此配置文件的目錄相同的目錄運行，除非--config標誌提供路徑。使用Vale CLI運行襯裡：

1. 在終端窗口中，導航到您的存儲庫。
2. 運行vale sync下載最新的Tech-Docs-linter軟件包，然後將其解壓縮到您的配置文件中列出的StylesPath 。
3. 運行命令vale .為了提起整個存儲庫或提供直接覆蓋目錄的途徑，例如： vale ./source/go-live

更新到最新技術文檔Linter Ruleset

如果將新規則添加到Tech Docs Linter規則集中，則可以在準備就緒時顛覆該存儲庫所使用的軟件包。可以通過：

1. 創建一個分支。
2. 在Vale配置文件中更新軟件包版本號。
3. 運行vale sync下載並解壓縮最新軟件包。
4. 運行vale ./source來測試襯裡。
5. 修復任何更改新規則集的投擲（最好是針對每個規則違規的一個提交）。
6. 在Vale Config File中使用最新版本號提出PR。

行為守則

請參考alphagov行為守則》。

執照

除非另有說明，否則代碼庫是根據MIT許可證發布的。這涵蓋了文檔中的代碼庫和任何示例代碼。

該文檔為©Crown版權，並根據公開政府3.0許可的條款獲得。