Sphinxのドキュメントサンプル:業務利用例

日本UNIXユーザ会 2010年12月勉強会 (2010/12/3)の発表で使用したドキュメントを作りたくなってしまう魔法のツール Sphinxのデモで使用したドキュメントのひな形です。プレゼンテーションの全文はドキュメントを作りたくなってしまう魔法のツール Sphinxにあります。

デモで使用したSphinxのドキュメントサンプルを以下のリンクからダウンロード出来ます。

Step1 Sphinxの初期ドキュメントから始める

初期ドキュメントから始めると言っても、sphinx-quickstartコマンドで作成しただけの状態のファイルを共有しても、それではドキュメントを書いてくれないでしょう。これは「どう書いて良いか分からない」を解消していません。

../../_images/slide1.png

Step2 ドキュメントの最初のアウトプットを作成

前述の、読者のターゲット別に章節の構成をおおまかに用意します。この段階でドキュメントの大枠は用意できました。そして、いつでもドキュメントを作成、変更、HTML出力まで動作するようになりました。しかしもう一歩踏み込んで、既に分かっている情報を書いてしまいましょう。

../../_images/slide2.png

Step3 既に分かっている情報を書き足します

マネージャー、設計者、開発者それぞれに必要となる情報を用意します。ここまでの情報がそろっていれば、プロジェクト開始時にメンバーに情報が行き渡らないということはあまりなくなると思います。

../../_images/slide3.png

Step4 段階的にドキュメントに記載していく

段階的にドキュメントに記載していくことで、ドキュメントが成長していきます。記載していく途中途中で、章の構成もどんどん変わっていってかまいません。

../../_images/slide4.png
  • Tips

    • 対象読者と話の焦点を常に意識する
    • 読者が異なる場合や焦点が異なる場合は適切なページに記載する、リンクする
    • ホワイトボードに記載したことはデジカメで撮って画像にする。図の清書は必要になるまで不要。
    • 新しい専門用語が出てきたら、都度glossaryとして記載する
    • 専門用語を使うときはglossaryへのリンクとなるようマークアップする
    • 最終ドキュメントに含めない予定のメモも全てreStructuredTextで書きAppendixに入れておく
    • Appendixの内容はぶら下げる先ができたら移動するなど、時々整理します