アジャイルのドキュメント一覧 -

アジャイル開発で必要なドキュメント一覧

アジャイル開発にて、ソフトウェアエンジニアが書かなければならないドキュメントには次のようなものがある

コードのコメントに含まれるリファレンス
デザインドキュメント
チュートリアル
概念的ドキュメント
ランディングページ

これらの全てのドキュメントについて、後ほど詳細に解説していく

アジャイル開発で必要なドキュメント一覧
アジャイル開発におけるリファレンス
デザインドキュメント
- デザインドキュメントの長さ
デザインドキュメントの構造について
チュートリアル
ランディングページ
参考

アジャイル開発におけるリファレンス

大半のリファレンスドキュメントには、コードと別のドキュメンテーションとして提供されている場合でも、大元はコードと同じ場所にあるコメントから自動的に生成されます。

Java や Python などの一部の言語には、このリファレンスドキュメントの生成を容易にするための特定のフレームワーク(Javadoc、PyDoc、GoDoc)があります。

C++などの他の言語には標準的なドキュメント生成ライブラリの実装はありませんが、C++は.ccファイルからヘッダーまたは.hファイルを分離しているため、多くの場合ヘッダーファイルが文書を記述するのに自然な場所です。

コードと同じ場所にリファレンスの元を置くことは、情報源の重複を防止します。 コードと同じ箇所にリファレンスの元を置くことで情報源が単一になり、結果としてアジャイル開発の目標である透明性を達成できるのである。

イテレーションの途中で顧客やPMから、「事前に伝えられていた動作と実装が真逆になっているけど？」と言われたら、おそらくそれは情報源がバラバラになっている証拠です。

ソースコードを検索するためには？

GoogleではSearch Codeと呼ばれる自社製のツールを使用しています。

このツールではコード内部を検索するだけでなく、そのコードの元の定義からドキュメントを探ることが可能なのです。

コードの定義とドキュメントが並んでいることは、ドキュメンテーションの発見と保守が容易になります。

すなわち、ドキュメントとコードを同じ場所に置いておくことで、ソース由来のまちがいの指摘から、ドキュメントの修正と通知までのプロセスが格段に速くなるのです。

このようなツールを使用することでアジャイルの求める透明性や速度にまた一歩近づけます。

ファイルのリファレンス

リファレンスルールその1

Googleでのコードファイルのほぼ全てには、ファイルコメントを含まなければならないというルールがあります。

// ------------------------------------------------
// str_cat.h
// ------------------------------------------------
//
// このヘッダー ファイルには、効率的に連結および追加するための関数が含まれています
// 文字列: StrCat() および StrAppend()。これらのルーチン内の作業のほとんどは、
// 実際には、設計された特別な AlphaNum 型を使用して処理されます
// への変換を効率的に管理するパラメーター型として使用する
// 文字列であり、上記の操作でコピーを回避します。

一般的に、このファイルコメントには読んでいるコード内部に何が入っているかについての概要から始まる。

よって、書くべき内容はこのファイルが達成するべき内容と目次である。

クラス単位のリファレンス

リファレンスルールその2

Googleにおける全ての公開クラス(すなわちpublic装飾がついたクラス)は、そのクラス自身についてのコメント、そしてそのクラスの重要なメソッドと使い方についてのコメントを含んでいなければならない

テンプレート

このクラスは「」というメソッドを持ち、「」という役割を持つ。

具体例

// ------------------------------------------------ ------------------------------
// AlphaNum
// ------------------------------------------------ ------------------------------
///
// AlphaNum クラスは、StrCat() および
// StrAppend()、数値、ブール値、および
// 16 進値 (Hex 型を使用) を文字列に変換します。

この場合、AlphaNumクラスが「StrCat」「StrAppend」という関数を含んでいることと、いくつかのオブジェクトを文字列に変換する役割を持つことが明記されています。

関数単位のリファレンス

リファレンスルールその3

Googleでは、全ての自由関数もしくはクラスの公開メソッドは、その関数が何を行うかを説明するコメントも含んでいなければならない。

関数のリファレンスは、その利用の能動的な動き強調し、その関数が行うことととその返り値を説明する。

関数コメントを動詞で締め括ることで、APIのタイトルでの一貫性が保たれることに注意しておくこと。「連結する、削除する、作成する」など、動詞を読むだけで良い。コードの読み手がAPIを素早く流し読みする場面で、その関数の使用が適切かどうかを判断しやすいようにする。

テンプレート

この関数は、「」を受け取り、「動詞」をします。「返り値の説明」を「オブジェクトの型」として返します。

具体例

// StrCat()
///
// 区切り文字を使用せずに、指定された文字列または数値をマージします。
// マージされた結果を文字列として返します。
…

デザインドキュメント

アジャイル色よりもGoogleという企業の文化の色が強いが、ともかく Googleのエンジニアリング文化の重要な要素の1つに、ソフトウェア設計を定義するためのデザインドキュメントがあります。

アプリケーションの主要な開発者がプロジェクトに着手する前に作成する比較的非公式なドキュメントです。

デザインドキュメントには、コードよりも簡潔で理解しやすく、問題と解決策をより高い抽象化されたレベルで伝えることができるため、ライフサイクルの早い段階で問題を解決するのに役に立ちます。

この「ソフトウェアのライフサイクルに柔軟に対応できる」という意味で、デザインドキュメントはアジャイル開発の一助となるはずです。

デザインドキュメントの長さ

アジャイル開発においては速度が旨となります。（この速度であらゆる問題に対処するわけです）

デザインドキュメントは、十分に詳細でありつつも、多忙な人々が実際に読めるように十分に短くする必要があります。

大規模なプロジェクトでは、約10～20ページに収まることを想定します。

また、1～3 ページの「ミニデザインドキュメント」を作成することは可能なはずです。これは、アジャイルプロジェクトで段階的な改善やサブタスクを行う場合に特に役立ちます。

デザインドキュメントの構造について

やるべきことリストとやらないことリスト

これはアジャイル開発の「デッキインセプション」にも含まれてる内容です。

このプロジェクトが達成するべきことの箇条書きの短いリスト「やることリスト」
このプロジェクトのスコープ外についての箇条書きの短いリスト「やらないことリスト」

「やらないことリスト」は合理的にゴールになり得るが、今回のゴールではないことを明示的に選択されていることに注意してください。

すなわち「やらないことリスト」にはなぜその判断に至ったのかが裏付けされていなければなりません。

概要

デザインドキュメントは解決策を提案し、特定の解決策がそれらの目標を最もよく満たす理由を示す場所です。

ソフトウェアアーキテクチャ

アーキテクチャ図を書くことは

技術的な要素を全て書き出し
その中に眠るリスクを全て洗い出す

ということを可能にします。

このアーキテクチャ図は、「開発者全員が同じ図面を想像しているだろう」という状態でも、必ず書いてください

API一覧

設計中のシステムがAPIを公開している場合は、それの一覧をスケッチしてみましょう。

おそらく、APIの設計の問題点に気づくチャンスになります。（APIのリファレンスを作ってから問題点に気づく、というのは多くの開発者が経験してきたことだと思います）

ただし、APIはすぐに改修されると思いますので、簡単なスケッチで構いません

データストレージ

データを保存するシステムは、これがどのように発生するかについて議論する必要があります。

完全なスキーマ定義をコピーして貼り付けることは避けるべきです。代わりにデザインとそのトレードオフに関連する部分（つまりスケッチ）に注目してください。

チュートリアル

ソフトウェアエンジニアは皆、できるだけチームに追いつきたい、役に立ちたいと思っているだろう。その場合、新しいプロジェクトの構成を説明するチュートリアルがあることは非常に重要です。何かの前提無しにエンジニアが「実践的な何か」を作り出せるような「Hello World」ドキュメントが用意されているのが相応しい。

チュートリアルはいつ描けばいいのか？

チュートリアルがまだ存在しない場合、チュートリアルを作成するのに最適なタイミングは最初にチームに参加したときです。

チュートリアルを書くときにはいくつかコツがあります。

脇にExcelをおきながら、何かの作業を行うたびに、あるいは行う前にスクリーンショットをとって貯めておきましょう。（画像ファイルと画面が一致するかどうか確認しながら作業を進めることは次の人への手助けにつながるはずです）
また、そのプロセス中にどんな間違いをしたか、どうして間違えたか、どうすれば次の人が間違えないかもメモしておきましょう。
重要なのは、途中で行う必要があることすべてを書き出すことです。
番号をつけておきましょう。そして全体の作業量がどれだけあるのが、現時点でどれだけの作業が完了したのか、を把握できるようにしましょう。自分の立ち位置を把握することは心理的安全につながるはずです。

よくないチュートリアル

以下で、あまり良くないチュートリアルと改善するべき点を挙げました）

1. http://example.com のサーバーからパッケージをダウンロードします。

2. シェルスクリプトをホーム ディレクトリにコピーします。**（どのスクリプトか不明）**

3. シェルスクリプトを実行する

4. foobar システムは認証システムと通信します **（不要）**

5. 認証されると、foobar は「baz」という名前の新しいデータベースをブートストラップします。**（サーバーが作業するのか?開発者が作業するのか?不明）**

6. コマンドラインで SQL コマンドを実行して「baz」をテストする **(テストの項目は何でどうするのがあるべき状態か？)**

7. タイプ: CREATE DATABASE my_foobar_db;

全体として、チュートリアルでユーザーから見える入力か出力があるのであれば、それを別の行に表示するべきである

良いチュートリアル

先ほどよりも格段に読みやすくなりましたね

1. http://example.com のサーバーからパッケージをダウンロードします。

`$ curl -I http://example.com`

2. シェル スクリプトをホーム ディレクトリにコピーします。

`$ cp foobar.sh ~`

3. ホーム ディレクトリでシェル スクリプトを実行します。

`$ cd ~; foobar.sh`

4. foobar システムは、最初に認証システムと通信します。認証されると、foobar は「baz」という名前の新しいデータベースを作成し、入力シェルを開きます。

5. コマンド ラインで SQL コマンドを実行して、「baz」をテストします。

`baz:$ CREATE DATABASE my_foobar_db;`