2つのステップで書く¶

Peter Elbowは著書"Writing with Power"(洋書)の中で、どんな人も、一回で完璧な文章を書くことはほぼ不可能であるということを説明しています。多くの開発者がドキュメントを書くときに、直接完全なテキストを書き上げようとするところに問題があります。これを改善するプラクティスの一つは、毎回2行だけ文章を書き、読み返して修正するというものです。これをすると、文章の作成と、テキストのスタイルの両方にフォーカスすることになります。

この方法には、脳には負担がかかりすぎるのと、結果が最良のものになるとは限らないという問題があります。内容を十分に考える前に、多くの時間とエネルギーをテキストのスタイルと形を整えるのに費やしてしまうからです。

別の方法は、まずはスタイルと構成を考えないで、中身にフォーカスするというものです。どのように書くかは別にして、全ての考えをまず紙の上に書き出します。開発者は、流れるように次々と書いていきます。文法まちがいを理由に手を止めてはいけません。文法は内容に関わることではないからです。考えていることを紙に書き出し続けている限りは、文の意味がほとんど理解できなくても問題はありません。まずは言いたいことを、大ざっぱに分類しながら書き出すことだけに集中します。

そうしていくと、開発者は自分が言いたかった内容にのみ意識を集中させることができるため、最初に考えていたよりも多くの内容が頭の中から次々に出てくるようになります。

この方法には、直接は関係ないトピックに関するアイディアも容易に出てきやすくなるという、別の効果もあります。そのようなアイディアが出てきた場合には、別の紙かファイルに書き出すようにしましょう。そのように残しておけばその内容が失われることはありませんし、今取りかかっているメインのドキュメントに、すぐに戻ることができます。

二番目のステップは、今書いた全文を読み返して、多くの人に分かりやすいように磨き上げる作業になります。テキストを磨くというのは、スタイルを良くして、間違いを直し、構成を直し、重複した情報を整理するということです。

ドキュメントを書くために使用できる時間が限られているときは、この二つのステップ(一番目のステップで内容を書き出し、二番目のステップでテキストを掃除してまとめる)の時間のうち、二番目の時間を削って一番目と同じ程度にすると良いでしょう。

読者のターゲットを明確にする¶

テキストを書き始める時に、ドキュメント作成者が考えておくべきシンプルな質問が一つだけあります。それは「誰がそのドキュメントを読むのか？」です。

これは、いつも明確になっているわけではありません。ソフトウェアを構成するパーツがどのように動作しているかを説明しているドキュメントであれば、そのコードを入手して使用するすべての人に対して書かれる場合がほとんどでしょう。読者は、問題に対して適切な技術的解決策を探しているマネージャかもしれませんし、そのコードに新しい機能を追加する必要のある開発者かもしれません。設計者は、アーキテクチャの視点から、そのパッケージが自分のニーズに合っているかどうかを知るために読むでしょう。

ドキュメントを書く場合には、シンプルなルールを適用しましょう。それぞれのテキストには、1種類の読者のみを設定すべきです。

この哲学を持ってドキュメント作成に取りかかると作業が簡単になります。ドキュメント作成者はその読者が何をしているのかを正確に知ることができるため、簡潔で正確なドキュメントを提供できるようになります。幅広い読者に合わせようとして漠然としたドキュメントになることがなくなります。

それぞれのドキュメントが何のために書かれているのか、というのを紹介する文をそれぞれ1行だけ付けるのは良いプラクティスです。このコンパクトな説明によって、読者を適切なドキュメントに誘導することができます:

AtomisatorはRSSフィードを取得して、フィルタリングを行ってから
データベースに格納する製品です。

あなたが開発者なら、APIの説明(api.txt)をお読み下さい。

あなたがマネージャなら、機能リストとFAQ(features.txt)をお読みください。

設計者であれば、アーキテクチャとインフラストラクチャに関するメモ
(arch.txt)をお読み下さい。

このように、読者の思っていることに注意することで、良いドキュメントが作成できるようになります。

シンプルなスタイルを使用する¶

Seth Godinはマーケティングの分野における、ベストセラー作家の一人です。あなたが興味を持つと思われる"Unleashing the Ideavirus"(邦題: バイラルマーケティング-アイディアバイルスを解き放て！-)はインターネット上で無料で読むことができます(http://en.wikipedia.org/wiki/Unleashing_the_Ideavirus)。

彼は最近、自分の本が売れた理由を理解しようと、ブログ上で分析を行いました。彼はマーケティングの分野のすべてのベストセラーのリストを作成し、それぞれの本の一文当たりの平均ワード数を比較しました。

彼が発見したのは、彼の本の文は平均13ワードで、他の本と比べて一番短かったということでした。このシンプルな事実から、読者は長くてスタイリッシュな文よりも、短くて簡単な文を好むことが証明できた、と彼は説明しています。

文章を短く保つと、読者が内容を読み取って、処理をして理解するために必要な脳のエネルギー消費が少なくなります。技術的なドキュメントの目的は、読者に対してソフトウェアのガイドを提供することです。フィクションの物語を書いているわけではないため、Stephen Kingの小説よりも、電子レンジの説明書の方に近い文章にすべきです。

シンプルにするために覚えておくべきTipsは次の通りです:

• シンプルな文を使用しましょう。2行以上にわたる文であってはなりません。

• 各段落は、最長でも3つか4つの行で構成され、主要な1つの考えのみを説明します。ウサギ(=その考え)が呼吸できるように。 [1]

• 何度も繰り返さないようにしましょう。読者に理解させようとする場所で、何度も何度も考えを繰り返すような、ジャーナリスト的なスタイルは避けましょう。

• 複雑な時制は不要です。現在形で十分です。

• 本当に優れたドキュメント作成者でなければ、ジョークを入れてはいけません。技術文書をユーモラスにするのは困難です。それをマスターしている作成者は少ししかいません。どうしてもジョークを入れたい場合にはコードサンプルに限定してください。そうすれば満足が行くでしょう。

脚注

情報のスコープを絞る¶

ソフトウェアの世界では、悪いドキュメントかどうかを簡単に見分けるサインがあります。あなたは今、とあるドキュメントの中から情報を探そうとしています。どこかに存在することはわかっているのですが、それを見つけることができません。目次をじっと解読しても、grepコマンドを使っていくつかの単語の組み合わせを試してファイルの中を検索しても、あなたがが探しているものは見つけることはできません。

このような事態は、ドキュメント作成者がテキストを話題ごとにきちんとまとめていないときに発生します。その作成者はかなり大量の情報を提供しているかもしれませんが、整理せずにただ1つに集めたにすぎません。たとえば、読者がアプリケーションの概要を知りたがっているときには、APIのドキュメントを読む必要はありません。APIドキュメントには細かい低レベルの説明しかないからです。

関連のあるセクションにパラグラフをきちんと納め、意味のあるタイトルを付けると、このような事態を避けることができます。ドキュメントのタイトルは、コンテンツを統合した短いフレーズにします。

良いタイトルが付いていれば、すべてのセクションのタイトルを集めるだけで目次ができあがります。

タイトルを考えるときには、「私はこのセクションを見つけるために、どのような文をタイプしてGoogleで検索するだろうか？」と自分に質問するという、簡単な習慣を身につけましょう。

実在するようなコードのサンプルを使用する¶

Foo, Barを利用するのは悪い習慣です。読者がコードサンプルを読んでそのコード片を理解しようとしたときに、現実的なサンプルでなければ理解はしにくくなります。

なぜ現実世界のサンプルを使用しないのでしょうか？コードのサンプルを実際のプログラムにカット・アンド・ペーストできるようにするのは一般的なプラクティスです。

悪い使用例のサンプルです。

パースのための関数が用意されています::

   >>> from atomisator.parser import parse

次のようにしてパースの関数を利用することができます:

   >>> stuff = parse('some-feed.xml')
   >>> stuff.next()
   {'title': 'foo', 'content': 'blabla'}

次の例は良いサンプルです。トップレベルの関数として提供されているパーサ関数が、どのようなフィード内容を返すかを知ることができるでしょう。

パースのための関数が用意されています::

    >>> from atomisator.parser import parse

次のようにしてパースの関数を利用することができます::

    >>> my_feed = parse('http://tarekziade.wordpress.com/feed')
    >>> my_feed.next()
    {'title': 'eight tips to start with python',
     'content': 'The first tip is..., ...'}

わずかな違いに対して強調しすぎだと思われるかもしれませんが、この差はドキュメントの便利さにとっての大きな差となります。読者はこのサンプルのコードをコピーして、簡単にインタラクティブシェル上で動かしてみることができます。その結果、このパーサがパラメータにURLを指定して動作するということを理解し、ブログのエントリーを含むイテレータを返すということが理解できるでしょう。

なるべく少なく、かつ十分なドキュメント¶

ほとんどのアジャイルな方法論においては、ドキュメントは一番大切なものではありません。詳細に書かれたドキュメントを書くよりも、実際に動作するソフトウェアを作ることの方が大切です。Scott Amblerによって書かれた『アジャイルモデリング――XPと統一プロセスを補完するプラクティス(原題"Agile Modeling"』（訳：株式会社オージス総研、翔泳社刊）には、次のような良いプラクティスが書かれています。「エクストリーム・プログラミングと統一プロセスの両方にとって効果的なプラクティスは、徹底的にドキュメントを作成していくのではなく、本当に必要なドキュメントのニーズを明確にすることである」

たとえば、Atomisatorがどのように動作しているのかをシステム管理者に説明するには、ドキュメントが1つあれば十分です。どのようにそのツールを設定して実行すればいいのかという方法以外の情報はまったく必要ありません。このドキュメントのスコープは次の質問に答えることができる範囲に限定されます:

私はどのようにすれば、Atomisatorを自分のサーバ上で実行できるのか？

スコープと読者層のほかに、それぞれのセクションのサイズを数ページに制限するというのも良いアイディアです。ほとんどの場合、考えがうまくまとまれば、それぞれのセクションは4ページ以内に納まるでしょう。もしもそれ以上に必要であれば、そのソフトウェアは複雑すぎて、説明したり使用することが困難であるということを意味します。

脚注

テンプレートの使用¶

Wikipediaのページはすべて似たような構成をしています。右側にデータのサマリーが書かれたボックスがあります。ドキュメントの最初にはリンクの張られた目次があり、各テキストに飛ぶことができます。ページの末尾には、参考情報のセクションがあります。

ユーザはその構成に見慣れています。実際、ユーザーは目次を素早く見ることで、自分の探している情報が載っているかどうかがわかるということを知っています。もしも見つからなければ、参考情報のセクションを探し、そのトピックを扱っている他のウェブサイトを探しに行きます。このやり方は、Wikipediaのどのページでも使用することができます。そして、Wikipediaにおいては、この方法を取る方が効率がよいと言うことを学ぶでしょう。

そのため、テンプレートを使用して、ドキュメントを共通パターンに強制することで、読者がドキュメントを読む効率が良くなります。構造に慣れると素早く読む方法が分かります。

ドキュメントの種類ごとにテンプレートを用意すると、ドキュメントを素早く書くことも可能になります。

本章では、ソフトウェア開発に必要な様々な種類のドキュメントについて見ていきます。次に、Pasterを利用したドキュメントのひな形の作成についても紹介します。しかし、まず最初に、Pythonのドキュメント作成で使用すべき、マークアップの文法の説明から行っていきます。