公開：2022年10月12日
1分で読めます
GitLabにおける「Docs as Code」の5つのポイント
この記事では、GitLabのテクニカルライターがDocs-as-Codeワークフローを用いてGitLabをどのように利用しているのかを、5つのポイントに分けてご紹介します。
GitLabでは、「Docs-as-Code」ワークフローを使うことで、単一のプラットフォームとしてGitLabを使ってGitLabのドキュメントを作成・管理しています。少しわかりづらいでしょうか？
GitLabのテクニカルライティングチームは、GitLabを使ってGitLabドキュメントの計画、作成、レビュー、編集、公開までを一貫して行っています。Docs-as-Codeワークフローを導入することで、熱意ある少人数の効率的な備えたチームで膨大な量のコンテンツを生み出すことが可能になっています。
Docs-as-Codeに馴染みがない方のために、簡単にご説明します。
Docs-as-Codeとは、製品ドキュメントの開発や公開を、ソフトウェアコードの開発と同じツールやプロセスを用いて行う手法です。ドキュメントファイルはコードファイルと同じリポジトリで管理され、バージョン管理も可能です。
ご自身が所属する組織でGitLabにDocs-as-Codeワークフローを採用できるか気になっている場合は、ぜひこの記事を読み進めてください。GitLabチームが実践している5つの方法をまとめてご紹介します。
GitLabを使ってGitLabの機能とドキュメントの更新を計画
プロダクトマネージャー、UXデザイナー、エンジニア、品質管理チームは連携して機能の開発計画を立てます。リリースを計画する際に、Kanbanボードを使ったり、サードパーティのツールでイシューを作成したりするチームも多いかと思います。
GitLabでは、エピックとイシューイシューを使って作業計画を立て、イシューボードを用いて進捗を管理します。GitLabでは透明性を重視しているため、計画に関するディスカッションも含め、こうした情報には誰もがアクセスできるようになっています。そのため、テクニカルライティングチームは開発の進行状況をいつでも把握できる環境にあります。
大規模なドキュメント作業を行う場合、その進捗をGitLabで管理し、変更はGitLabを使用して行い、イシューが完了したらGitLabで完了マークを付けます。1年後に変更の理由を振り返りたい場合、GitLabで検索すれば、誰がどのような理由で変更を加えたのかを確認できます。現在、複数のツールを使って作業している方は、一度にすべてを一元的に管理できる環境を想像してみてください。より迅速かつ効率的に作業を進められると思いませんか？通常ならメールやウェブサイト、Slackを見て回って見失ったディスカッションを探すのに時間を費やしていたかもしれませんが、それがすべてGitLabに集約されているため、無駄な時間を省けます。
もしWikiを愛用していて、不可欠だという場合でもご安心ください。GitLabにはWiki機能も備わっています。
GitLabを使ってドキュメントのフィードバックをやりとり
ライターとして一定の経験がある方なら、コンテンツのレビューを依頼する際の手間をよくご存じでしょう。
GitLabでは、デベロッパーがすべての新機能に関するコンテンツの初稿を作成します。そして、そのコンテンツはコードと同じリポジトリに保存されます。機能に関するドキュメントは、GitLabの開発プロセスにおける「完了の定義（DoD）」の一部です。デベロッパーはその初稿をライターに割り当て、ライターはそれをレビューし、提案を加え、アイデアや必要な編集内容を作成者であるライターに返します。
ライター自身もコンテンツの変更を行う場合は、マージリクエスト（MR）を作成します。MRを作成するのがライターであれ、デベロッパーであれ、サポートエンジニアであれ、コミュニティのコントリビューターであれ、誰でもお互いの作業に簡単にコメントできる仕組みになっています。
マージリクエストでは、「提案」ボタンを選択するだけで簡単にコメントできます。1行、または複数行単位でコメントを付けることができ、変更や編集を提案できます。MRを作成した本人は、その変更を簡単に適用したり、別の提案を作成し議論したりできます。他のユーザーを会話に招待するには、コメントにユーザー名を入力します。すると、相手にコメントがGitLabのTo Doアイテムとして表示されます。このようにして、あらゆる変更について議論でき、透明性があり、誰もが参加できる環境が整っています。
ドキュメントの内容はMarkdown形式で記述されており、プレーンテキストに似ているため、ファイルのバージョン間の違いを簡単に確認でき、誰がどの変更をコミットしたのかも把握できます。
PDFやWordドキュメント、Googleドキュメントでコメント機能を使ってレビューを行った経験がある方も多いでしょう。このワークフローを試すと、どれだけ効率的に作業が進むかを実感できるはずです。古いバージョンのドキュメントが使われることもなく、誰かのコメントを意図せず削除してしまうようなこともありません。
また、変更の理由を知りたい場合も、ページの履歴を簡単に確認でき、特定の行について誰が「担当者」であるかもすぐに確認できます。
複数のバージョンのPDFドキュメントを管理したり、誰がどの変更を提案したのかを探したりする必要はもうありません。すべての管理がGitLab内で完結するため、手間が省けます。
GitLabを使ってドキュメントの内容をプレビュー
GitLabでは、ドキュメントサイトのコンテンツをローカルで生成するツールを提供していますが、マージリクエストから直接ドキュメントサイトを簡単に共有することもできます。新しいアイデアを試していて、それを誰かに見せたい場合は、マージリクエストを開き、「アプリレビュー」を生成すると、変更されたドキュメントサイトを公開URLで確認できるようになります。
変更内容を確認でき、イテレーションを行うことも、そのままコミットすることも可能です。次にこれに関連する、GitLabの便利な機能をもうひとつご紹介します。
GitLabを使ってすべてのコンテンツの変更をテスト
ドキュメント内のリンクをテストしたり、スペルや文法のルールを確認したりするために、サードパーティーのツールが使っている方も多いかと思います。
GitLabでは、Nanoc（リンクのテスト用）やVale（スペル・文法の確認用）などのサードパーティツールを使用していますが、これらのツールもGitLabに統合でき、ライターのワークフローにも組み込むことができます。
各ライターは、自身のローカル環境でこれらのツールを使用し、ドキュメントの読解レベルや文法修正などをすべて確認できます。これらのツールを持っていないコントリビューターには、パイプラインで自動的にテストを実行し、すべてのコミットに対して結果を表示する仕組みを導入しています。
デベロッパーとして、文章の専門知識に自信がない場合、マージリクエストのパイプラインで重要な文法やブランディングルールに従っていないために処理が進まないことがあります。GitLabでは、さまざまなルールを定め、それぞれに優先順位を付けています。そのため、スタイルガイドや単語リストを用意しているだけでなく、テストを実行してコンテンツがそうしたルールに沿ったものになっているかを確認しています。
GitLabを使ってHTML出力を生成し、その出力をGitLab Pagesでホスト
GitLabのCI/CDパイプラインは、Markdown形式のコンテンツをHTMLに変換してコンパイルします。その後、出力内容をGitLab Pagesを介して、docs.gitlab.comにホストします。
パイプラインによって出力を生成することで、必要なときにいつでもドキュメントサイトを更新できます。製品は月に一度リリースされますが、ドキュメントサイトは1時間ごとに更新されます。そのため、docs.gitlab.comでは常に最新の情報が提供されており、時にはリリース前の情報も公開されます。開発計画や実装に関するイシューはGitLabの透明性の方針に基づき公開されているため、機能の事前発表を行うことに問題はありません。
このように、GitLabが「Docs-as-Code」ワークフローを重視する理由は数多くあります。最初はドキュメント作成を1つのツールで完結させることに慣れずに戸惑うかもしれませんが、GitLabはライター全員のワークフローを最初から最後までサポートしており、長年の実績がその効果を証明しています。
GitLabでのテクニカルライティングにおける「Docs-as-Code」ワークフローについて詳しくは、次の動画をご視聴ください。