📘
AIと考えた最強のドキュメント戦略 ~ドキュメントピラミッド~
ディスクレーマー
意外と良さげなものはできましたが、ネタ記事です。
たたき台にしつつちゃんとしたものを誰か作ってください。
ドキュメントにもなにかいい感じの指針がほしい
ドキュメントって作るのも保守するのも面倒だったりしますが、ちゃんと作ってあると結局後で助かるんですよね。
なので、そのための指針があると嬉しいなあと皆さん常日頃思っているはずです。
アナロジーを働かせよう
作るのも保守するのも少し面倒だが、ちゃんと作ってあると助かるものとして他に思いつくものとして テスト がありますよね。
そちらには 「テストピラミッド」 という有名な指針があります。
以下の画像がわかりやすいです。
How to Test your Events? より引用
これと同じ発想をすれば、ドキュメント作成でも良い指針が得られるのではないでしょうか？
ChatGPT と考えてみる
とはいえ、私個人が適当に決めても誰も納得しないでしょう。
そこで今流行りの人類の叡智である ChatGPT（無課金板）と考えてみることにしました。
まずはテストピラミッドを把握しているかを確認
私: テストピラミッドについて教えて下さい
ChatGPT:
テストピラミッドとは、ソフトウェア開発プロセスにおけるテストの段階を階層化して表現したモデルのことです。
ソフトウェアのテストには、異なるレベルのテストがあり、それぞれが異なる目的と範囲を持っています。
テストピラミッドは、これらのテストを階層的に組織化し、効率的かつ効果的なテスト戦略を作成するためのモデルとして使用されます。
一般的に、テストピラミッドは以下の3つのレベルに分かれています。
1. ユニットテスト:
ソフトウェアの最小単位である関数やメソッドなどの単体をテストするレベルです。
通常、開発者が行います。
ユニットテストは、ソフトウェアの品質を確保し、バグを早期に発見するために重要な役割を果たします。
2. 統合テスト:
ユニットテストで単体で動作確認されたコンポーネントを組み合わせて、それらの相互作用をテストするレベルです。
異なるコンポーネントの組み合わせによるバグやインタフェースの問題を検出するために使用されます。
3. システムテスト:
ソフトウェア全体の機能や性能をテストするレベルです。
ユーザーの視点からのテストを行い、システム全体の正確性や信頼性を確認します。
これらのレベルを組み合わせてテストピラミッドを形成し、ユニットテストを最も多く実施し、統合テストを中程度に、システムテストを最小限に実施することで、効率的かつ効果的なテストを実施することができます。
また、テストピラミッドは、アジャイル開発やDevOpsなどの現代的なソフトウェア開発手法において、品質を確保するための重要なモデルとして広く使用されています。
良さそうですね。
本題を聞いてみる
私: テストピラミッドのようなものをドキュメントでも考えたいです。ドキュメントピラミッドとはどのようなものになりますか？
ChatGPT:
「ドキュメントピラミッド」は、テストピラミッドとは異なるコンセプトですが、類似のアイデアを適用することができます。
ドキュメントピラミッドは、ドキュメントのタイプやレベルを階層的に整理し、適切なバランスを持ったドキュメンテーション戦略を示します。
一般的に、ドキュメントピラミッドは以下の3つのレベルに分かれています。
1. コアドキュメント（Core Documentation）
ソフトウェアやシステムの基本的なドキュメントを指します。
例えば、システム全体の設計文書、アーキテクチャの概要、APIドキュメントなどが含まれます。
これらのドキュメントは、システム全体の理解や開発者間のコラボレーションを促進し、システムの全体像を提供します。
2. ユーザードキュメント（User Documentation）
システムの利用者向けに作成されたドキュメントを指します。
例えば、ユーザーガイド、マニュアル、チュートリアルなどが含まれます。
これらのドキュメントは、システムの利用方法や操作手順を提供し、ユーザーがシステムを効果的に利用できるようにします。
3. サポートドキュメント（Support Documentation）
システムのトラブルシューティングやサポートのためのドキュメントを指します。
例えば、FAQ、トラブルシューティングガイド、サポート記事などが含まれます。
これらのドキュメントは、問題解決やサポートの効率化を支援し、ユーザーが問題に対処できるようにします。
これらのドキュメントレベルを適切に組み合わせることで、効率的で網羅的なドキュメンテーション戦略を実現することができます。
コアドキュメントを基礎にし、ユーザードキュメントを重視し、サポートドキュメントを必要に応じて提供することで、システムの理解や利用の円滑化、サポートの向上を図ることができます。
また、ドキュメントの自動化やテスト、バージョン管理などのベストプラクティスも適用することで、高品質なドキュメンテーションを実現することができます。
中々悪くなさそうですが、コアドキュメントは開発者目線、それ以外はユーザ目線で混ざってしまっているように感じます。
開発者向けとユーザ向けに分けてもらう
私: ユーザ目線と開発者目線が混ざってしまっているように感じるので、それぞれに分けて作ってもらえますか？
ChatGPT:
もちろんです！以下は、ユーザードキュメントと開発者向けドキュメントを箇条書きで詳しく示したものです。
【ユーザードキュメント】
- ユーザーガイド:
- ソフトウェアの使い方や操作方法の解説を提供
- マニュアルやハンドブック形式で、利用者がソフトウェアを効果的に使用できるようにする
- チュートリアル:
- ソフトウェアの初めての利用者向けに、ステップバイステップの手順やサンプルを提供
- 実践的なガイドを通じて、利用者がソフトウェアを迅速に理解し、使用できるようにする
- リファレンス:
- ソフトウェアの機能やオプションの詳細な説明を提供
- APIリファレンスやコマンドラインオプションの一覧などを含み、利用者が必要な情報を参照できるようにする
【開発者向けドキュメント】
- コーディングガイド:
- ソフトウェアの開発に関するガイドラインやルール、コーディングスタイルなどを提供
- 開発者が統一されたスタイルでコードを書き、保守性や品質を向上させるための情報を提供する
- アーキテクチャ:
- システム全体の設計文書やアーキテクチャの概要、設計上の考慮事項などを提供
- ソフトウェアの設計や構成に関する情報を提供し、開発者がシステム全体の設計に理解を深められるようにする
- APIドキュメント:
- ソフトウェアのAPI仕様や利用方法の詳細な説明を提供
- 開発者がAPIを利用してソフトウェアを連携や拡張するための情報を提供する
結構良くなりました。ただここでいう開発者は API の利用者のような印象を受けます。
ここでふと「変数名は最小のドキュメント」という誰かがどこかで書いていた言葉を思い出しました。
そこでそのエッセンスを入れてもらいました。
開発者向けドキュメント
私（メモミスって消しちゃったのでここだけ思い出して書いてます）:
開発者向けドキュメントのピラミッドの最下層は適切な関数名とか変数名とかだと思うんですよね。それでピラミッド構造を書き換えてもらえますか？
ChatGPT:
以下に再度、開発者向けドキュメントのピラミッド構造を箇条書きで詳しく示します。
【開発者向けドキュメント】
- コーディングガイド:
- ソフトウェアの開発に関するガイドラインやルール、コーディングスタイルなどを提供
- コードの品質向上や保守性の向上を促進するための情報を提供する
- アーキテクチャ:
- システム全体の設計文書やアーキテクチャの概要、設計上の考慮事項などを提供
- ソフトウェアの設計や構成に関する情報を提供し、システム全体の設計に理解を深められるようにする
- APIドキュメント:
- ソフトウェアのAPI仕様や利用方法の詳細な説明を提供
- 開発者がAPIを利用してソフトウェアを連携や拡張するための情報を提供する
- 関数/メソッドドキュメント:
- 各関数やメソッドの説明や利用方法、引数や戻り値の詳細な情報を提供
- 開発者が関数やメソッドの使い方を理解し、効果的な利用を行えるようにする
- 変数/定数ドキュメント:
- 各変数や定数の説明や用途、スコープや初期値の情報を提供
- 開発者が変数や定数の役割を理解し、適切に利用できるようにする
以上のように、開発者向けドキュメントのピラミッド構造には、コーディングガイドやアーキテクチャ情報からAPIドキュメント、さらに関数/メソッドドキュメントや変数/定数ドキュメントへと段階的に詳細な情報が提供されています。
これにより、開発者はソフトウェア全体の設計やAPIの利用方法を理解しつつ、関数や変数の詳細な情報を参照することで、効果的な開発作業を行えるようになります。
適切な関数名や変数名つけようという意図とはずれちゃいましたがまあこんなもんでしょう。
ユーザ向けドキュメント
一応改めて出力してもらいます。
私: ユーザドキュメントもピラミット構造にしてもらえますか？
ChatGPT:
もちろんです。ユーザ向けドキュメントのピラミッド構造を以下のように考えることができます。
最上層: ユーザガイド
- アプリケーション全体の使い方や概要を説明したガイド。
- 一般的にユーザ向けの最上位のドキュメントであり、全体のコンセプトや機能の概要、操作方法などを解説します。
中間層: 機能ごとのドキュメント
- アプリケーションの機能ごとに分けたドキュメント。
- 各機能の詳細な使い方や操作方法、設定方法、注意事項などを解説します。
- ユーザガイドで説明した概要を、具体的な機能ごとに詳細に解説したものとなります。
最下層: リファレンスドキュメント
- アプリケーションの詳細な機能や設定の情報をまとめたリファレンスドキュメント。
- APIの仕様やパラメータ、コマンドの使用方法、設定ファイルの詳細な説明などが含まれます。
- 開発者向けのドキュメントであり、ユーザが直接触れることは少ないかもしれませんが、システム管理者や上級ユーザ向けの情報を提供します。
このように、ユーザ向けドキュメントもピラミッド構造を持つことで、全体の構造が明確になり、ユーザが必要な情報を効率的に探し出しやすくなります。最上層では全体の概要を、中間層では機能ごとの詳細な情報を、最下層ではリファレンス情報を提供することで、ユーザが必要な情報にスムーズにアクセスできるようになります。
これは結構まともなのでは？
結論
その後もゴニャゴニャ対話を続け（コピペが面倒になった）、以下の形に落ち着きました。なかなか素敵ではないでしょうか。
開発者向け
最上層: コアドキュメント（Core Documentation）
- ソフトウェアやシステムの基本的なドキュメントを指します。
- システム全体の設計文書、アーキテクチャの概要、APIドキュメントなどが含まれます。
- システム全体の理解や開発者間のコラボレーションを促進し、システムの全体像を提供します。
中間層: モジュールドキュメント（Module Documentation）
- システムを構成するモジュールやコンポーネントごとに分けたドキュメントです。
- 各モジュールの機能やインターフェース、設計思想、実装方法などを解説します。
- モジュールごとのコーディングに関する情報を提供し、モジュール間の関係や依存関係を理解しやすくします。
最下層: ソースコードドキュメント（Source Code Documentation）
- システムの実際のソースコードにコメントやドキュメンテーションを追加したドキュメントです。
- ソースコードの機能や処理の流れ、関数やクラスの使い方、変数や定数の説明などを解説します。
- 適切な変数名やコメントなどの具体的なコーディング情報を提供し、ソースコードの理解やメンテナンスを支援します。
このように、コアドキュメントを最上層に置き、モジュールドキュメントを中間層に配置し、ソースコードドキュメントを最下層に置くことで、システム全体の理解からモジュールレベルの設計情報、具体的なソースコード情報まで段階的に提供し、開発者が効果的にシステムを理解し、開発を進めることができるようになります。
ユーザ向け
最上層: ユーザガイド（User Guide）
- システムの利用者向けに、アプリケーション全体の使い方や概要、チュートリアルなどを解説したドキュメントです。
- 最上層には、システム全体の使い方や基本的な操作方法、画面の説明などを提供します。
- ユーザがシステムを効果的に利用できるように、全体像や基本的な情報を提供します。
中間層: 機能ごとのドキュメント（Feature-specific Documentation）
- システムの利用者向けに、機能ごとの使い方や設定手順、ユースケースなどを解説したドキュメントです。
- 機能ごとにドキュメントを作成し、より詳細な情報を提供します。
- ユーザが特定の機能を効果的に利用できるように、機能に関連する情報を提供します。
最下層: リファレンスドキュメント（Reference Documentation）
- システムの利用者向けに、詳細な機能設定やFAQ、トラブルシューティング情報をまとめたドキュメントです。
- 最下層には、システムの設定や機能に関する詳細な情報やFAQ、トラブルシューティング情報を提供します。
- ユーザがより高度な操作やトラブルの解決を行えるように、詳細な情報を提供します。
このように、ユーザ向けドキュメントのピラミッド構造は、最上層にはアプリケーション全体の使い方や概要を、中間層には機能ごとのドキュメントを、最下層にはリファレンスドキュメントを配置することで、ユーザがシステムを理解し、必要な情報を効率的に参照できるように構築されています。
また、最下層には詳細な情報やFAQ、トラブルシューティング情報をまとめることで、ユーザがより高度な操作や問題の解決を行えるようにサポートします。
余談
『エンジニアのためのドキュメントライティング』という本を最近買ったのですが積読してます。
ChatGPT で遊ぶより、多分それ読んだほうがいいでしょうね。
Discussion