Docs as Codeのススメ

最近、実際にコーディングしてモノを作る開発業務から少し離れて、
システム仕様検討やアーキ仕様検討などの上流工程を担当することが多くなりました。

プロセス上の制約もあり、このあたりのドキュメントはExcel、 Wordに依存しているのですが、生産性の観点や管理のしにくさから、あまりこれらのツールを使いたくないと思ってしまいます。 そこで、なるべくDocs as Codeの考え方を取り入れてドキュメントを作成・管理するよう実践しています。

前置き

ぶっちゃけ、多くのエンジニアにとっては当たり前じゃんって内容かもしれません。
しかし、少なくともこのような考え方がまだまだ浸透していない現状もあると思うので、私なりの考え方と実践例をまとめています。

そもそものソフト開発に対する思い・考え

世は"ソフトウェアファースト"という考えのもと、あらゆる企業がソフトウェアで新たな価値を生み出すことが必達となる時代になっています。
また、最近生成AIの台頭もあり、ソフト開発はそのプロセスから環境まで大きな変革が起こっています。
それによって、求められるエンジニアの役割も変わっていくと思います。

	従来	これから
エンジニア	専門的な技術ノウハウ・スキルを持って課題解決に協力	専門的な技術ノウハウ・スキルは十分AIでも実現可能。 価値を生むためのアイデアとそれを迅速に実現するための仕組みを考えることに注力する
非エンジニア	ユーザ目線で価値を考え、アイディエーションすることに注力し、 開発はエンジニアに任せる	アイデアをいち早くローコード、 ノーコードツールでプロトタイピングし、 迅速に価値検証する。 またはそのまま製品化してしまう。

もはや、 ソフト設計・実装をできることがエンジニアの専門分野ではなくなってきている、競合の多い領域にシフトしていかなければいけない現実があります。
エンジニアとして勝ち残るためには、これまで非エンジニアが実施してきたような上流の目線で価値の実現をしなければなりません。　　

それを実現するために、

• 従来の専門的な技術ノウハウ・スキルを活かす
• 生成AIを最大限に活用して成果を生み出す
• 無駄な作業を省略し、アイディエーションに集中する

ことが重要だと考えています。

と、これが、上記の実現性に欠ける(と思っている)ExcelやWordでドキュメントを作成したくない理由です。

Docs as Code とは

「Docs as Code」とは、ソフトウェア開発におけるコードと同じようにドキュメントを扱う考え方です。

• VSCodeなどコーディングと同じツールチェーンを使用してドキュメントを作成・編集する。
• Markdownなどでドキュメントをテキストベースで管理する。
• Gitなどでバージョン管理システムを使用してドキュメントの変更履歴を管理する。
• CI/CDパイプラインなどでドキュメントの生成や配布を自動化する。

これは前述している、エンジニアとして勝ち残るためのポイントすべてを網羅できるアプローチだと考えます。
もちろん、従来のプロセスとのギャップについても考えなければいけませんが、コードと同じように扱えれば、あとでツール等でいくらでも対応できます。

実践例

現在、主な成果物はシステム仕様書、アーキテクチャ仕様書です。以下のツールを組み合わせて実装しています:

	ツール	用途
OS	Ubuntu 24.04(WSL)	開発環境
エディタ	VSCode	ドキュメント作成・編集
生成AI	GitHub Copilot　(Claude Haiku 4.5)	ドキュメント作成支援
ドキュメント形式	Markdown	ドキュメントのフォーマット
図表形式	drawio、 PlantUML	図表のフォーマット
バージョン管理	Gitlab	ドキュメントのバージョン管理
CI/CD	Gitlab CI/CD	ドキュメント生成・配布の自動化

OS: Ubuntu 24.04(WSL)

作業PC自体はWindowsなのですが、WSL上にUbuntu 24.04をインストールして使用しています。
これは、単純にLinux環境に慣れているからというのもありますが、ルーティン作業をシェルスクリプトで自動化したり、その環境をコンテナ化して共有したりといったことが容易にできるためです。

エディタ: VSCode

エディタはVSCodeを使用しています。
完全フリーソフトでありながら、非常に多機能で拡張性も高く、ドキュメント作成に必要なほとんどの機能をプラグインで補完可能です。

生成AI: GitHub Copilot、 Claude Haiku 4.5

VSCodeとの親和性が高いGitHub Copilotを導入しています。
現状モデルに特にこだわりはないのですが、単純にレートが安いため、Claude Haiku 4。5を使用しています。
(品質にこだわるなら、きちんと特化したモデルを選定すべきだと思います...)

ドキュメント形式: Markdown

ドキュメントのフォーマットにはMarkdownを使用しています。マークアップ言語として非常にシンプルでありながら、見出し、箇条書き、コードブロック、画像挿入などの基本的な構文をサポートしており、ドキュメント作成に必要な要素を十分にカバーしています。
また、VSCode上でリアルタイムにプレビューできるため、参照しながらのレビューも容易です。

図表形式: drawio、 puml

図表のフォーマットにはdrawioとpumlを使用しています。

• drawio:
  VSCodeの拡張機能(Drawio Integration)を使用して、エディタ内で直接編集可能なXMLベースのフォーマットです。これまでExcelやWordで作成していた図表を、同様の操作感で作成できます。
  
• PlantUML:
  テキストベースのフォーマットです。シーケンス図、クラス図、アクティビティ図など、さまざまなUML図を簡単に作成できます。コードとして管理できるため、バージョン管理や自動生成にも適しています。
  

バージョン管理: Gitlab

ドキュメントのバージョン管理にはGitlabを使用しています。これは単純に既存の開発プロセスで使用しているためです。

CI/CD: Gitlab CI/CD

ドキュメントの生成や配布の自動化にはGitlab CI/CDを使用しています。
Markdownで作成したドキュメントはチャプターごとに分割して管理しているのですが、CI/CDパイプラインを使用すれば、これらを一括で結合し、WORDやPDFなどの最終的なドキュメント形式に変換することが可能です。

サンプルドキュメント　

(今回のために生成AIでさっと作成したもの。機密情報は含まれていません)

メリット

だいたいの作業がVSCode上で完結する。

この仕組みを導入すれば、ドキュメント作成に必要なほとんどの作業をVSCode上で完結できます。
不要なツールの起動や切り替えが不要になり、軽量で高速なドキュメント作成が可能になります。
また、ちょっとしたルーティン作業もVSCodeのターミナル上でシェルスクリプト等を実行すれば済むため、作業効率が大幅に向上します。

生成AIが理解しやすい形式でドキュメントを作成できる。

テキストベースの形式でドキュメントは生成AIによる恩恵を最大限に受けられます。

• タブ補完によるドキュメント作成支援
• ルールに基づいたドキュメントレビュー、 自動校正
• 自然言語によるドキュメント修正指示

が可能になり、ドキュメント作成の効率化と品質向上が期待できます。

体裁よりも内容に集中できる。

Markdownなどのシンプルなフォーマットを使用することで、ドキュメントの内容に集中できます。
私はExcelやWordを使用する場合、ある程度の体裁ルールがあるにしても、どうしても体裁やレイアウトに気を取られてしまい、内容に集中できないことが多々あります。
Markdownのような構造化されたシンプルなフォーマットであれば、
複雑なフォーマット設定やレイアウト調整に煩わされることなく、アイディエーションや内容の充実に注力できます。

強力なCIツールが利用できる。

GitLab CI/CDなどの強力なCIツールを利用して、ドキュメントの生成や配布を自動化できます。

デメリット

チームメンバーに慣れてもらう必要がある。

Docs as Codeのアプローチを採用するには、チームメンバー全員がこの方法に慣れる必要があります。
MarkdownやGitなどのツールに不慣れなメンバーがいる場合、最初は抵抗感を覚えたり、学習コストが発生するかもしれません。
が、 実際生成AIも活用できる環境であれば、正直そこまで高いハードルにはならないと考えています。

既存のドキュメント資産を活用しにくい。

既存のExcelやWordで作成されたドキュメント資産をMarkdown形式に変換するには、手動での変換作業が必要になる場合があります。
ただし、最近では生成AIを活用して、これらのドキュメントをMarkdown形式に自動変換するツールも登場してきているため、これらを活用すれば、変換作業の負担を軽減できる可能性があります。

そのほか便利なツール

Marp for VSCode:

MarkdownでPowerPointのようなスライドを作成できる拡張機能です。
Markdownのフォーマットでは少しプレゼンなどでの共有に向きませんが、Marpを使用すれば、Markdown形式でスライドを簡単に作成、出力できます。
ちょっとしたプレゼン資料を作成する際に非常に便利なので、とても重宝しています。
また、CSSでスライドのデザインをカスタマイズできるため、企業のブランドガイドラインに合わせたスライド作成も可能です。

まとめ

以上のように、Docs as Codeのアプローチは、エンジニアとしての技術力を最大限に活かしつつ、生成AIの力を借りて効率的にドキュメントを作成・管理するための有効な手段です。今後のソフトウェア開発において、またエンジニアとしての価値を高めるためにも、積極的に取り込んでいくべき考え方だと思います。
テキストベースで作成している以上、現状のプロセスに合わせこむことはいくらでもできますので、まずは小さく始めてみることをお勧めします。

参考にさせていただいたページ

https://www。writethedocs。org/guide/docs-as-code/
https://qiita。com/tikamoto/items/c05a5c117c78fb7a4e47