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许可的条款获得。