Docs as Codeってなんだ？ ― ドキュメント制作はどう変わるのか – Arkanos Insights 

「Docs as Code」って、結局なんですか？

ドキュメント制作に関する情報を調べていると、「Docs as Code」という言葉を見かけることがあります。

直訳すれば「コードとしてのドキュメント」。ソフトウェアのソースコードを扱うように、ドキュメントも制作・管理しようという考え方です。

しかし、この説明だけでは、何が変わるのかよく分かりません。

Markdownで文章を書くことでしょうか。Gitで変更履歴を管理することでしょうか。それとも、プログラムを使ってマニュアルを自動生成することでしょうか。

いずれもDocs as Codeで使われることのある手法ですが、それぞれがDocs as Codeそのものを指しているわけではありません。

今回は、この考え方を整理したうえで、従来のドキュメント制作と何が違うのか、どのような場面でメリットがあるのか、そして、わざわざ導入する必要があるのかを考えてみます。

Docs as Codeは、ファイル形式ではなく制作の考え方

Docs as Codeとは、ソフトウェア開発で用いられる手法をドキュメント制作にも取り入れる考え方です。

例えば、次のような制作方法が考えられます。

• ドキュメントをMarkdownなどのテキスト形式で作成する
• Gitで変更履歴を管理する
• 変更内容をレビューし、承認してから反映する
• プログラムによって記述内容やリンクなどを検証する
• 変更を契機にHTMLなどの公開用データを生成する

ソフトウェア開発に携わる人であれば、ソースコードの制作・管理方法に近いと感じるのではないでしょうか。

ただし、これらをすべて導入しなければDocs as Codeと呼べない、というわけではありません。ドキュメントの性質や制作体制に合わせて、必要な手法を組み合わせることになります。

ここで区別しておきたいのは、Markdownは記述形式、Gitは変更履歴などを管理するための仕組み、Docs as Codeはそれらを活用した制作・運用の考え方だという点です。

Markdownで文章を書くだけでも、Gitでファイルを管理するだけでも、ドキュメント制作の工程全体が変わるとは限りません。

重要なのは、執筆からレビュー、検証、公開までを、どのような仕組みでつなぐかということです。

実は、Arkanos Insightsでも似たことをしていました

少し身近な例を挙げてみます。

Arkanos Insightsの記事は、まずMarkdownで原稿を作成し、Gitで変更履歴を管理しています。原稿を修正しても過去の内容を確認でき、複数の記事をまとめて管理することもできます。

公開時にはWordPressに記事を登録しているため、執筆から公開までを一貫して自動化しているわけではありません。それでも、テキスト形式で原稿を作成し、Gitで管理するという点では、Docs as Codeの考え方の一部を取り入れていることになります。

実際、この記事の構成を考えているときに、「そういえば、Insightsの原稿もMarkdownで書いてGit管理しているな」と気づきました。

つまり、Docs as Codeという言葉を知らなくても、目的に合った制作方法を選んだ結果、似た運用になっていることはあるわけです。

では、MarkdownとGitを使っていれば、それだけでドキュメント制作の問題が解決するのでしょうか。

でも、それってCCMSでもできるのでは？

ここで、従来のドキュメント制作に携わっている方なら、疑問に思うかもしれません。

「変更履歴の管理やレビュー、HTMLへの出力なら、今の制作環境でもやっているのでは？」

そのとおりです。

例えば、DITAなどの構造化ドキュメントを扱うCCMS（Component Content Management System）では、コンテンツの管理や再利用、バージョン管理、承認、翻訳、複数形式への出力などを、一つの制作環境の中で扱うことができます。

Docs as Codeで挙げられる機能の多くは、ドキュメント制作の世界でまったく新しく登場したものではありません。

違いがあるとすれば、ソフトウェア開発で使っているツールや作業の進め方を、ドキュメント制作にも活用するという発想です。

開発者が普段からGitを使っているのであれば、ドキュメントも同じ環境で管理できます。ソースコードとドキュメントの変更を関連づけたり、既存のレビューや自動処理の仕組みを利用したりすることも考えられます。

一方、すでにCCMSを利用している制作現場では、Gitを導入しただけで大きなメリットが生まれるとは限りません。既存のCCMSで実現できている管理機能を、別のツールで重複して持つことにもなりかねないからです。

また、Docs as CodeはCCMSの単純な代替品ではありません。両者は一部の機能や目的が重なりますが、制作体制や管理対象、必要な機能によって適した構成は異なります。

では、Docs as Codeが具体的に役立つのは、どのような場面でしょうか。

開発者が作った仕様書から、マニュアルを生成する

一つの例として、企業向けソフトウェアの製品マニュアルを考えてみます。

開発者は、製品仕様書をMarkdownで作成し、Gitで管理しています。仕様書には、内部処理の説明から画面操作、設定項目まで、さまざまな情報が含まれています。

一方、利用者向けのマニュアルには、そのうち操作方法や設定手順などの情報が必要です。

従来であれば、仕様書を参照しながら、別途マニュアルを執筆する工程を設けることもあるでしょう。

しかし、仕様書の中でマニュアルに必要な情報をあらかじめ識別できるようにしておけば、別の方法が考えられます。

例えば、マニュアルに掲載する範囲を <!-- manual:start --> と <!-- manual:end --> で囲んでおき、スクリプトでその部分だけを抽出する。抽出したMarkdownをHTMLに変換すれば、簡易的なマニュアルを生成できます。

図：開発者が管理する仕様書からHTMLマニュアルを生成する例

この仕組みなら、開発者が管理する仕様書を情報の正本とし、マニュアルを別途執筆・管理する工程を減らせる可能性があります。

また、仕様書の更新に合わせてマニュアルを再生成する仕組みを設ければ、仕様書とマニュアルの内容が食い違うリスクも減らせます。

もちろん、仕様書の文章がそのまま利用者向けの説明として成立することが前提です。操作手順の分かりやすさや情報の過不足については、公開前に確認する必要があります。

それでも、開発者が日常的に使っているMarkdownやGitをそのまま活用できるなら、新たに大がかりな制作環境を構築せずに、マニュアル制作の工程を簡素化できる場合があります。

ここでAIを使う必要はあるのか？

仕様書からマニュアルを生成するというと、AIを使った自動化を思い浮かべるかもしれません。

確かに、仕様書の意味を読み取り、利用者に必要な情報を判断したり、説明文を書き換えたりするのであれば、AIの活用は選択肢になります。

しかし、必要な情報が決められたタグで識別されていて、その部分を取り出すだけなら、簡単なスクリプトで十分です。

そこにAIを使っても、必ずしも処理が簡単になるとは限りません。出力結果の確認や、意図しない省略・変更への対策が必要になる場合もあります。

AIは、従来のプログラムでは難しかったことを実現するための選択肢であって、従来のプログラムで十分な処理を置き換えるためのものではない。

Docs as Codeの実現にAIが必須というわけでもありません。まず必要な処理を整理し、それに適した方法を選ぶことが重要です。

どんなドキュメントにも適しているわけではない

先ほどの例では、開発者がMarkdownやGitを日常的に利用していることが前提でした。

では、制作担当者がテクニカルライターで、Gitを使った経験がない場合はどうでしょうか。

Gitの操作や開発者向けのレビュー手順を新たに習得する必要があるなら、既存の制作環境を使う方が効率的かもしれません。

また、次のような要件がある場合も、慎重な検討が必要です。

• 多言語展開を前提とし、翻訳対象や翻訳履歴を管理する
• 複数製品・機種・仕向け地でコンテンツを再利用する
• 複雑な版管理や承認工程がある
• HTMLだけでなく、レイアウト要件の厳しいPDFも制作する
• 開発者以外の多くの担当者が執筆・編集に参加する

これらの要件をDocs as Codeで実現できない、という意味ではありません。

ただし、必要な管理機能や制作環境を個別に組み合わせていけば、仕組みの構築・運用そのものが大きな仕事になる可能性があります。

すでにCCMSなどで実現できているのであれば、同じ機能を別の方法で作り直す必要があるのか、考えなければなりません。

反対に、開発者が作成する比較的シンプルなドキュメントに対して、多機能なCCMSを導入することが過剰になる場合もあるでしょう。

大切なのは、Docs as CodeかCCMSかという言葉の選択ではなく、誰が、何を、どのように制作・管理し、何を公開する必要があるのかを明確にすることです。

「Docs as Codeを導入すること」を目的にしない

Docs as Codeという言葉だけを見ると、従来のドキュメント制作を新しい方法に置き換える話のように感じるかもしれません。

しかし、実際には、ソフトウェア開発の環境や手法をドキュメント制作にも活用することで、工程を簡素化したり、開発とドキュメントの更新を連動させたりする考え方です。

開発者が普段から使っている環境をそのまま活用できるのであれば、大きなメリットが生まれる可能性があります。

一方、すでに必要な制作・管理の仕組みが整っている現場では、無理に取り入れる必要はありません。

Markdownを使うことも、Gitを導入することも、AIで文章を生成することも、それ自体が目的ではないはずです。

まずは、今のドキュメント制作で何が課題になっているのかを整理する。そのうえで、Docs as Codeの考え方が課題の解決につながるのであれば、必要な部分を取り入れる。

新しい言葉に合わせて制作方法を変えるのではなく、実現したい制作方法に合わせて、使う技術を選ぶ。

Docs as Codeも、そのための選択肢の一つとして考えるのがよいのではないでしょうか。