資料

1. ドキュメントの覚醒
第一回OTM
鈴木隆志

2. ドキュメント
• ドキュメント
設計書
手順書
ソフトウェアのドキュメント
引継ぎ用の資料
• ドキュメント作成ツールで出てくるのは
Excel
Word

3. Officeの長所
• 環境設定
→大体のPCに入っている
• 使える人が多い
→わかりやすいUI、使ったことがある人が多い
• 大量の便利機能
→文法チェック(word)
表計算(Excel)
図、画像の扱いやすさ

4. Officeの短所
• ドキュメントの管理
→バックアップファイルを作成して保存
大量の日付が後ろについたファイル
→バージョン管理ソフトともあまり相性が良くない

5. Officeの短所
• 巨大化するファイル
→一つのxls、docでシート、ページを増やした結果、重く編集し難いファイル
• 前のバージョンとの比較
→バイナリファイルなので比較しようとしてもできない
最近は文字比較、画像比較のツールがあったりなかったり
• 複数人による一つのファイルの編集
→シート、ページが増えていくと複数人で編集したくなるが、
同時に編集はできない、マージはできないので比べながらコピーペーストになる
• レイアウトの調整
→最初に調整してあっても崩れる
一度崩れると見た目では判別しにくい物を地道に調整することになる

6. Office以外に何か使えるものはないのか

7. Sphinx使ってみませんか？

8. Sphinxって何？
• Python製のドキュメントツール
• オープンソース（BSDライセンス）
→フリーソフト
• Python リファレンス、ホームページ、書籍等で使われている

9. Sphinxって何？
• テキストファイルを様々な形式に変換することができるツール
restファイル Sphinx
html
ePub
LaTeX
PDF

10. Sphinxって何？
• 形式はreST(reStructedText)というマークアップ言語
→マークアップ言語はhtml用なタグなどで修飾して太字等の属性をつける言語
reSTは書きやすい、見やすいマークアップ言語
============
プロジェクトタイトル（大見出し）
============
中見出し
=========
小見出し
-------------
#.自動採番箇条書き1
#.自動採番箇条書き2

11. Sphinxって何？
• 目次(toctree)ベースで文章構造を作る
それぞれのセクション（章）は別ファイルにわけることができる
目次
Sphinx
PDF、
ePub、html
1章
2章

12. Sphinxの長所
• ドキュメントの管理
→テキスト形式で作れるので、バージョン管理ソフトと相性がよい
バージョン管理ソフトを使うことで管理がしやすくなる
• 差分の確認
→テキスト形式なので、diffツールで差分の確認、マージ等が行いやすい
• スタイルの変更
→スタイルは全体にかけることができるので、統一、後の修正が行いやすい。
各ページ毎に変えることも可能
• 目次ベースの構造
→目次によって情報が探しやすくなる
各セクションが別のファイルにできるので、複数人で編集を行いやすい
別ファイルになることで1ファイルあたりの容量が減り編集しやすくなる
• Pythonで追加機能の作成が可能

13. Sphinxの短所
• 環境構築
→変換をかけるための環境を作る必要がある
• 言語（記法）の勉強
→reSTは分りやすいが、覚える必要がある
Officeはただ書くだけでよい
• 図、画像の挿入
→図、画像が別ファイルになりパス記載だけとなる
状態の確認をしながらの編集もOfficeと違いできない
→図は追加機能で可能だが、別の記法を覚える必要がある

14. Sphinxの短所
• 納品物
→HTML、PDFと良く扱うOffice以外が納品物となる
→納品先で編集される場合、環境を作ってもらう必要ができてしまう
→追加機能でdocで出力も一応可能
• 表計算、グラフの挿入
→表計算ソフトではないのでそういうことはできない

15. 簡単な比較
項目 Office Sphinx
環境構築 ○ △
作成・編集 △ △
図、画像 ○ △
バージョン管理 △ ○
スタイルの修正 △ ○
出力形式 ○ ○

16. 総括
OfficeをやめてSphinxを使いませんか？といきたいところですが、
短所を考えるとまだハードルが少し高い
今回のSphinxを含め、Tex、Wiki、MarkDown、DocBook等々用途によっては
Officeを超えるツールが今はある
ドキュメントはOfficeという固定観念にしばられず、ツールを使えるようになり
ましょう

17. 参考資料
• Sphinx 日本ユーザ会
http://sphinx-users.jp/index.html
• Sphinxを始めよう
http://sphinx-users.jp/gettingstarted/index.html
• 設計ドキュメント作成ツールとしてSphinxとReVIEWについて調べた
http://agnozingdays.hatenablog.com/entry/2013/01/04/154913