ドキュメントの構築¶
ドキュメントのヘルパーとガイドラインを提供すると、読者と作成者の両方の仕事を簡単に改善することができます。そのために、前節で学んできたことを活用していきます。
ドキュメント作成者の視点から考えると、ガイドと一緒に再利用可能なテンプレート集が提供され、それをプロジェクトの中でいつどのように使用するかという説明があると、この目標は達成できます。これをドキュメントポートフォリオと呼びます。
ドキュメント読者の視点から考えると、どのようなドキュメントが提供されるのかという展望が提供されると、楽にドキュメントを読むことができるようになりますし、必要なドキュメントを効率良く探して利用できるようになります。
ポートフォリオの構築¶
ソフトウェア開発のプロジェクトの中で作られるドキュメントには、ソースコードを直接参照するような低レベルなドキュメントから、アプリケーションの概要を伝える設計書まで、多くの種類があります。
実際に、Scott Amblerは、彼の著作の「アジャイルモデリング―XPと統一プロセスを補完するプラクティス」(詳しくは http://www.agilemodeling.com/essays/agileArchitecture.htm を参照)の中で、ドキュメントの種類に関する長いリストを定義しました。彼は早期の仕様書から、操作ドキュメントまでのポートフォリオを構築しています。プロジェクト管理のドキュメントもカバーされているので、ドキュメントに関するニーズのすべてが、標準化されたテンプレートのセットで構築されています。
実際に完璧なポートフォリオを考えようとすると、ソフトウェア開発に使用している方法論の影響を強く受けるため、本章では多くの人に共通なサブセットに限定して説明します。このサブセットを元にして、特定のニーズを満たすポートフォリオを作成することもできます。時間をかければ、あなたの仕事の習慣を網羅するような、効果的なポートフォリオを構築することもできるでしょう。
ソフトウェアのプロジェクトにおけるドキュメントの共通セットは、次の3つのカテゴリに分類されます:
設計: アーキテクチャの情報や、クラス図やデータベースのダイアグラムのような低レベルの設計情報を提供する、すべてのドキュメント。
使用方法: ソフトウェアをどのように使用するのかというのが書かれたドキュメント。このドキュメントは、クックブック、チュートリアル、モジュールレベルのヘルプなどの形態で提供されます。
運用: デプロイやアップグレード、ソフトウェアの運用に関するガイドラインを提供する。
設計¶
設計ドキュメントの目的は、ソフトウェアがどのように動作するのか、どのようにコードが組み立てられているのかを説明することです。開発者はシステムを理解するためにこのドキュメントを利用しますが、その他のアプリケーションがどのように動作しているのかを理解しようとしている人にとっても、良い入り口となります。
ソフトウェア開発には、次のような、さまざまな種類の設計ドキュメントがあります:
アーキテクチャ概要
データベースのモデル
依存関係、継承関係を含むクラス図
ユーザインタフェースのスケッチ
インフラストラクチャの説明
ほとんどのこれらのドキュメントは、いくつかのダイアグラムと、最小量のテキストで構成されます。ダイアグラムの描き方はチームやプロジェクトごとに定義されます。すばらしいドキュメントにするために、スタイルは一貫させましょう。
注釈
UMLは、ソフトウェア設計のほとんどの切り口をサポートする13種類の図を提供しています。おそらく、この中で一番使用されているのはクラス図ですが、UMLはソフトウェアのあらゆる面の説明に使用することができます。 http://en.wikipedia.org/wiki/Unified_Modeling_Language#Diagrams_overview を参照してください。 [1]
脚注
UMLのような特定の言語を、上から下まで完全に使って記述していくということは滅多にありません。多くのチームは、それぞれの経験から、独自の方法を作り上げています。そのようなチームでは、UMLや他のモデリング言語の中から、良いと思うものをピックアップした、独自のレシピを持っています。
アーキテクチャの概要を表す図を書く場合、単に四角い箱と矢印をホワイトボード上に描いて済ませてしまう設計者も数多くいます。決まったルールに従わないこともありますし、記録も取らないで消してしまうこともあります。また、Dia（http:////www.gnome.org/projects/dia//tt）や、Microsoft Visio（オープンソースでもフリーでもありません）などのシンプルなドロープログラムを使い、設計するのに必要な程度の最小の図を描く人もいます。本書の6章では、すべてのアーキテクチャの図を、OmniGraffle(http://www.omnigroup.com/products/omnigraffle/)を使って作成しています。
データベースのダイアグラムは使用するデータベースの種類に依存します。データモデリングソフトの中には、作図機能に加えて、テーブルと関連を自動的に生成してくれるものもあります。しかし、Pythonでは、こういったツールは大げさでしょう。SQLAlchemyなどのORマッパーを使用している場合、実装前にデータベースのモデルを説明するためには、6章でお見せしたように、フィールドリストが書かれたシンプルな箱をならべ、テーブル間の関連を付け足すだけで十分です。
クラス図には、UMLのクラス図をシンプルにしたものを使うことが多いでしょう。たとえば、Pythonではクラスにprotectedメンバを定義することはありません。そのため、アーキテクチャの概要を描くようなツールが定義されていれば、それで十分なことがほとんどです。
ユーザーインタフェースの図に関しては、作成しようとしているアプリケーションが、デスクトップアプリケーションか、それともWebアプリケーションかによって異なります。Webアプリケーションの場合には、ヘッダやフッタ、左右のパネルは全画面で共通なことが多いため、スクリーンの真ん中の部分だけを説明することが多いでしょう。人によっては、HTMLでプロトタイプを作ったり、スクリーンショットを作成します。デスクトップアプリケーションの場合には、プロトタイプの画面のスクリーンショットを撮ったり、GimpやPhotoshopといった画像をソフトを使用して、注釈付きのモックアップを作成するのが一般的です。
インフラストラクチャの概要を描いた図は、アーキテクチャの図に似ていますが、メールサーバやデータベース、その他のデータストリームなどの外部のシステムと、どのようにインタラクションを取っているのかという点に焦点を合わせて描いていきます。
共通テンプレート¶
このようなドキュメントを作成するときの重要なポイントは、ドキュメントのターゲットとなる読者を完全に把握し、内容のスコープを絞ることです。ドキュメント作成者への簡単なアドバイスも付いた、シンプルな構造を持つ、汎用テンプレートとして提供することで、これらを実現することができます。この構造には、次のものが含まれます。
タイトル
作成者
タグ(キーワード)
説明(概要)
対象(誰がこれを読むべきか？)
内容(図入り)
他のドキュメントへの参照
内容は、平均的な画面サイズを1024x768と想定した場合に、最大でも3〜4画面に収まる量にすべきです。もしもこれよりも多くなってしまったら、いくつかに分割するか、サマリーとしてまとめましょう。
テンプレートには、作成者の名前と、ドキュメントの評価を管理したり、分類を簡単にするためのタグも含まれています。これについては本章の後半で説明します。
ドキュメントのテンプレートを提供するために使用するツールはPasterです。pdp.skelsというファイルは、これまで説明してきた設計のテンプレートを実装しています。対象となるフォルダを指定し、いくつかの質問に答えるだけで、コードジェネレータと同じように使用できます。
$ paster create -t pbp_design_doc design
Selected and implied templates:
pbp.skels#pbp_design_doc A Design document
Variables:
egg: design
package: design
project: design
Enter title ['Title']: Database specifications for atomisator.db
Enter short_name ['recipe']: mappers
Enter author (Author name) ['John Doe']: Tarek
Enter keywords ['tag1 tag2']: database mapping sql
Creating template pbp_design_doc
Creating directory ./design
Copying +short_name+.txt_tmpl to ./design/mappers.txt
実行が完了すると、次のようなファイルが生成されます。
=========================================
Database specifications for atomisator.db
=========================================
:Author: Tarek
:Tags: database mapping sql
:abstract:
Write here a small abstract about your design document.
.. contents ::
Who should read this ?
::::::::::::::::::::::
Explain here who is the target readership.
Content
:::::::
Write your document here. Do not hesitate to split it in several
sections.
References
::::::::::
Put here references, and links to other documents.
注釈
訳注: pbp_design_doc テンプレートからは上記のように英語のドキュメントが生成されます。しかし、reSTドキュメントを日本語(utf-8)で書いても問題ありません。上記のドキュメントを日本語で書き直した場合は次のようになります。
================================
atomisator.db のデータベース仕様
================================
:著者: Tarek
:タグ: database mapping sql
:概要:
ここにこのドキュメントの概要を小さくまとめて書いて下さい。
.. contents::
このドキュメントの対象者
::::::::::::::::::::::::
ここで、このドキュメントが想定する読者を説明して下さい。
本文
::::
ここにドキュメントを書いて下さい。また、長い内容はためらわずに
複数の節に分けて書くようにして下さい。
参考文献
::::::::
ここに参考文献のリンク先やドキュメント名を記載して下さい。
使用方法¶
使用方法のドキュメントでは、ソフトウェアの一部分がどのように動作するのかを説明します。このドキュメントは、特定の機能がどのように動作するのかという低レベルな説明から、プログラム呼び出し時に使用するコマンドライン引数のような高レベルな説明まで含まれます。想定読者がコードを再利用しようとしている開発者なので、アプリケーションのフレームワークのドキュメントは、あらゆるドキュメントの中でもっとも重要なドキュメントになります。
このドキュメントは主に３種類あります:
レシピ: 何かを行うための方法を説明した、短いドキュメント。この種類のドキュメントは、特定の読者に絞ったものか、あるトピックに限定して焦点を当てたものになります。
チュートリアル: ソフトウェアの機能を使用するための方法を、一歩一歩説明したドキュメント。このドキュメントはレシピを参照します。また、それぞれの項目は、特定の読者のために書かれます。
モジュールヘルパー: モジュールに含まれる要素を説明する、低レベルなドキュメント。このドキュメントはモジュール越しに組み込みのヘルプを呼び出す場合に読まれます。
レシピ¶
レシピは特定の問題に対する解答や解決策を提供したりするドキュメントです。
例えば、ActiveStateのウェブサイトでは、Pythonクックブックオンラインが提供されています。
クックブックというのはレシピを集めたもので、Pythonで何か特定のことを行う方法について、開発者が自分で記述することができます(http://aspn.activestate.com/ASPN/PythonCookbook を参照)。これらのレシピは簡潔な、以下のような構造を持ちます。
タイトル
送信者
最終更新日
バージョン
カテゴリ
説明
ソースコード
議論(コードを説明するためのテキスト)
コメント(Webから)
ほとんどの場合、これらは１画面に収まる長さで、詳しい詳細説明が書かれません。この構造はソフトウェアに対する要望を記述する場合にもそのまま使用できますし、"対象読者"を追加して、"カテゴリ"を"タグ"に置き換えると、汎用的な構造として適用することができます。
タイトル(短い説明)
著者
タグ(キーワード)
これを読むべき人は誰か？
事前条件(例えば、先に読んでおくべきドキュメントなど)
問題(短い説明)
解決策(メインのテキスト。1?2画面に収まる量)
参照(他のドキュメントへのリンク)
更新日とバージョンは入れてもそれほど便利ではありません。プロジェクト内でソースコードのようにドキュメントも管理されていれば、後で見ることができるからです。
設計のテンプレートと同様に、pdp.skelsファイルを使用すると、このような構造をした、pdp_recipe_docテンプレートが使えるようになります。
$ paster create -t pbp_recipe_doc recipes
Selected and implied templates:
pbp.skels#pbp_recipe_doc A recipe
Variables:
egg: recipes
package: recipes
project: recipes
Enter title (use a short question): How to use atomisator.db
Enter short_name ['recipe'] : atomisator-db
Enter author (Author name) ['John Doe']: Tarek
Enter keywords ['tag1 tag2']: atomisator db
Creating template pbp_recipe_doc
Creating directory ./recipes
Copying +short_name+.txt_tmpl to ./recipes/atomisator-db.txt
実行が完了したら、ドキュメント作成者が内容を埋めていきます。
========================
How to use atomisator.db
========================
:Author: Tarek
:Tags: atomisator db
.. contents ::
Who should read this ?
::::::::::::::::::::::
Explain here who is the target readership.
Prerequisites
:::::::::::::
Put here the prerequisites for people to follow this recipe.
Problem
:::::::
Explain here the problem resolved in a few sentences.
Solution
::::::::
Put here the solution.
References
::::::::::
Put here references, and links to other recipes.
チュートリアル¶
チュートリアルはレシピと似ていますが、目的が異なります。チュートリアルは、個別の問題を解決するのではなく、アプリケーションの機能の使用方法をステップ・バイ・ステップで説明したものです。このドキュメントは、レシピよりもアプリケーションの多くの部分に触れることになるため、文章も長くなるでしょう。たとえば、DjangoはチュートリアルをWebサイト上で提供しています。初めてDjangoのアプリケーションを作成する方法について書かれたページ(http://www.djangoproject.com/documentation/tutorial01 を参照) [2] は、10ページ分の長さがあります。
脚注
ドキュメントの構造は次のようになります。
タイトル(短い文章)
著者
タグ(言葉)
説明(概要)
これを読むべき人は誰か？
事前条件(例えば、先に読んでおくべきドキュメントなど)
チュートリアル(メインのテキスト)
参照(他のドキュメントへのリンク)
ここで説明したような構造を持ったpdp_tutorial_docテンプレートも、pdp.skelsで提供されています。これも、設計のテンプレートと同じように使用することができます。
モジュールヘルパー¶
私たちのコレクションに最後に追加するテンプレートは、モジュールヘルパーのテンプレートです。モジュールヘルパーは、一つのモジュールについて書かれていて、そのモジュールに含まれる要素の説明と、使用方法のサンプルを提供します。
docstringを収集してモジュールのヘルプを作成する、pydocやEpydoc(http://epydoc.sourceforge.net を参照)といったツールを使うと、このようなドキュメントを自動的に構築することができます。APIの自動探索をベースにして、網羅的なドキュメントを作成することができます。この種類のドキュメントを提供しているPythonのフレームワークはかなりの数に上ります。実際にPloneがhttp://api.plone.orgで提供している情報は、モジュールヘルパーを収集することで、最新のドキュメントに維持されています。
このアプローチの主な問題は次の二点です。
ドキュメント全体に対して処理するときに、本当にドキュメントにしたい部分をスマートに選択する機能がない
ドキュメントが大量に含まれるため、コードが分かりにくくなる可能性がある
その上、モジュールの構成部品のいくつかの部分にまたがっていて、関数やクラスのdocstringに分解しにくいようなサンプルはモジュールのドキュメントとして提供されます。モジュールの先頭にテキストを書くと、そのモジュールのdocstringになるので、このような目的を達成することができます。しかし、これを行うとソースファイルがテキストのブロックとコードのブロックに分かれた構成になってしまいます。コードの行数が全体の50%を切ると、さらにわかりにくくなります。あなたがモジュールの作者であるとすれば、まったく問題はありません。しかし、ドキュメントではなくコードを読もうと思っている人は、docstring部分を飛ばさないといけなくなります。
他の方法としては、テキストを切り離すことです。手動で選択すると、どのPythonモジュールがモジュールヘルパーファイルを持っているかというのを決定することができます。ドキュメントはコードベースと切り離されるため、後で説明するように、ドキュメントの寿命を延ばすことができます。これが、Pythonのドキュメントの書き方になります。
ドキュメントとコードを分離することがdocstringよりも良いかどうかという点に関しては、多くの開発者の間で意見が分かれるところです。このアプローチを取るには、ドキュメント作成のプロセスを、完全に開発サイクルに統合しなければなりません。そうしなければ、ドキュメントはすぐに古新聞になってしまいます。docstringは、コードと使用例を近づけることによってこの問題に対処していますが、よりわかりやすいドキュメントの一部として使用できるテキストを提供するという、高いレベルの解決策を得ることはできません。
モジュールヘルパーのテンプレートは極めてシンプルで、内容に加えて、少量のメタデータが含まれる程度になっています。読者はそのモジュールを使用する開発者に限定されるため、だれが読むべきかという定義はここには含まれません。
タイトル(モジュール名)
著者
タグ(単語)
内容
注釈
次章では、doctestとモジュールヘルパーを利用したテスト駆動開発について言及します。
運用¶
運用に関するドキュメントは、ソフトウェアをどのように操作・運用すればいいのかを説明するのに使用されます。たとえば、
インストールとデプロイに関するドキュメント
管理ドキュメント
ユーザが問題に直面したときに手助けを行うための「良くある質問と答え(FAQ)」
ヘルプへの問い合わせ方法や、フィードバックを提供する方法を説明したドキュメント
これらのドキュメントはそれぞれが特異なものですが、テンプレートとしては前の部分で紹介した、チュートリアルのテンプレートを使用することができます。