Sphinx によるドキュメント執筆管理環境の検討

• 管理方法
  • メリット
  • 弱点
  • reStructuredText 執筆のコツ
• ディレクトリ構成

ここ数週間、隙間時間で悶々と考えていたことを吐き出す。

管理方法

一行で : 『Sphinx + VCS + Redmine + redmine_code_review』

• Sphinx でドキュメントを作成する
• ソースは VCS で管理
• ビルドしたドキュメントはドキュメントサーバーにデプロイ & 共有ディレクトリに格納
• ドキュメントのレビューは、 redmine_code_review プラグインを使い実施、管理する

※ VCS: できれば git + LFS, 次点で SVN

メリット

• Excel 共有と比べて
  • 誰がいつ変更したかが失われない
  • コミットコメントのルールを決めることで、「何故」も記録できる
  • redmine_code_review の仕組みを使うことで、レビュー記録も Redmine に集約できる
• Redmine の wiki と比べて
  • ビルドしてしまえばサーバーなしで参照できる

弱点

• Excel のようにシームレスな作図ができない
• reStructuredText がマイナー

reStructuredText 執筆のコツ

reStructuredText は、 tex, html などから続く『文章の意味と見た目が分離されているドキュメント』の一族。 執筆時には、文章構造に意識を集中すること。

これができると、あとは reStructuredText のルールに従って .rst に書き下していくだけで、誰でも同じ見た目の文章が作成できる。

Word, Excel と違い、編集するファイルの中に『見た目の情報』が存在しないため、 『うっかりフォントが変わった』や『ここだけインデントがずれた』 みたいなことがない。

ディレクトリ構成

docroot
   +- ワーキンググループ/
   |  +- ワーキンググループ_XXX/
   |  |  +- work/
   |  |  +- image/
   |  |  +- attachment/
   |  |  +- xxx.rst
   |  |  +- ワーキンググループの規模によってはサブディレクトリ作成も辞さない/
   |  |     +- work/
   |  |     +- image/
   |  |     +- attachment/
   |  |     +- yyy.rst
   |  |
   |  +- ワーキンググループ_ZZZ/
   |     +- ...(略)
   |
   +- 開発資料
   |  +- ...(略)
   |
   +- 運用資料
      +- ...(略)

• image : 本文に表示する画像(png)を格納
• work : image 加工用の元ネタを格納(xlsx, xcf 等)
• attachment : 添付ファイルを格納

うーん、もやもやする。