tech docs

gov.uk 1つのログイン技術文書

このレポは、gov.ukの1つのログインに搭載された政府部門の技術者を支援するドキュメントが含まれています。技術文書テンプレートを使用して公開されています。

コンテンツを変更します

Gov.uk One Login Technical Writingチームはこのドキュメントを所有しており、コンテンツの変更を承認する責任があります。ユーザー中心であり、GDSコンテンツ標準を満たすと書かれています。これは、次のことを意味します。

• コンテンツの計画、書き込み、管理に関するGov.ukガイダンス
• gov.ukスタイルガイド
• gov.ukテクニカルスタイルガイド
• その他の明確なライティングの原則

gov.uk 1つのログインで作業する場合は、コンテンツの変更に役立ち、ユーザーの動作に影響を与えない場合を除き、コンテンツの変更を支援するために、ハイテクライティングチームに連絡する必要があります。

小さなコンテンツの変更には次のものがあります。

• 理解を向上させるために説明を追加します
• コードサンプルの修正
• 壊れたリンクまたはタイプミスの修正

これらの変更を自分で行い、プルリクエストでハイテクライターのレビューをリクエストすることができます。変更が小さいかどうかわからない場合は、＃DI-Technical Writing Slackチャネルでお問い合わせください。

技術的な変更を加えます

オーケストレーションチームは、Tech Docsプラットフォームのメンテナンスと運用の健康を担当しています。そのスペースの変更を承認するために、それらを参照する必要があります。

例は次のとおりです。

• GitHubアクションワークフローの変更
• AWSの展開またはビルドインフラストラクチャの変更
• 依存関係の更新
• コンテンツを変更しないRubyは更新されます

ドキュメントの変更をプレビューします

ブラウザでドキュメントに作成した変更と追加をプレビューするには、このレポをクローンし、このレポのDockerFileを使用して、ローカルにRubyをセットアップすることなく、マシンでMiddlemanサーバーを実行します。

このセットアップにはライブリロードが有効になっているため、ソースディレクトリでファイルを編集するときに変更が適用されます。これの唯一の例外は、 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ファイルを編集できます。

図ごとに1つの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

gov.ukの1つのログイン技術ドキュメントを並べる

このリポジトリでは、ValeとGDS Tech DocsのLinter Rulesetを使用しています。

ローカルマシンにリナーを取り付けます

必要がある：

• HomeBrewをインストールします
• Valeをインストールします

コードエディターと糸くし

多くのコードエディターは、ドキュメントを更新する際にエラーを発生させる可能性のあるVale用の拡張機能またはプラグインを提供します。あなたはあなたのローカルマシンにValeをインストールする必要があります。

Vale Command Lineインターフェイス（CLI）との糸くず

デフォルトでは、 --configフラグにパスが提供されない限り、Valeはこの構成ファイルと同じディレクトリから実行する必要があります。 Vale CLIを使用してリンターを実行するには：

1. 端子ウィンドウで、リポジトリに移動します。
2. vale sync実行して、最新のTech-Docs-Linterパッケージをダウンロードし、これを構成ファイルにリストされているStylesPathに解凍します。
3. コマンドvale .リポジトリ全体をリントするか、ディレクトリへのパスを提供して、そのディレクトリのみをリントするためのパスを提供します： vale ./source/go-live

最新のTech Docs Linterルールセットへの更新

Tech Docs Linter Rulesetに新しいルールが追加された場合、準備ができたらこのリポジトリで使用されるパッケージをアップバージョンできます。ルールセットの後のバージョンは、テストして追加できます。

1. ブランチを作成します。
2. Vale Configファイルのパッケージバージョン番号を更新します。
3. vale sync実行して、最新のパッケージをダウンロードして解凍します。
4. vale ./source実行して、リナーをテストします。
5. 新しいルールセットがスローアップする変更を修正します（できれば各ルール違反に対して1つのコミット）。
6. Vale Configファイルの最新バージョン番号を使用してPRを上げます。

行動規範

alphagov行動規範を参照してください。

ライセンス

特に明記しない限り、コードベースはMITライセンスの下でリリースされます。これは、ドキュメント内のコードベースとサンプルコードの両方をカバーします。

ドキュメントは©Crown Copyrightであり、Open Government 3.0ライセンスの条件の下で入手できます。