10章: プロジェクトのドキュメント作成¶

ドキュメント作成は、開発者、ときにはマネージャもさぼってしまいがちな作業です。開発サイクルの終了に向かうにつれて時間が無くなったり、自分は文章を書くのが苦手だと考えている人がいたりするのが、さぼってしまう原因です。確かに文章を書くのが苦手な人もいますが、大多数の開発者とマネージャはすばらしいドキュメントを書くことができます。

急いで書かれた文書が集めれた結果、内容が整理されていないドキュメントが作られてしまうこともあります。開発者はたいてい、この手の仕事をするのが好きではありません。既存のドキュメントをアップデートしなければならない場合には、さらに事態は悪化します。マネージャがそのような事態にどう対処すればいいのか分からない場合、多くのプロジェクトでは貧相で、内容の古いドキュメントしか提供できないということになります。

しかし、プロジェクトの開始時にドキュメント作成プロセスを整備し、ドキュメントをソフトウェアのコードのモジュールと同じように扱うようにすると、ドキュメントを書くのがもっと簡単になります。いくつかのルールに従うと、書くのが楽しくなる場合すらあります。

本章では次のような内容を通じて、プロジェクトのドキュメントを書き始めるためのTipsを紹介していきます:

• 技術的な文章を書くためのベストプラクティスをまとめた、７つのルール
• ほとんどのPythonプロジェクトで使用されている、reStructuredTextというプレーンテキストのテキストマークアップ文法の入門
• 良いドキュメントを構築するためのガイド