前編でSphinxと競合ツールの比較をしたので 今回は実際にどうやって導入していくかを考えました。 refs https://github.com/gosyujin/slideshare/blob/6d5ba7ab36e4426a4239b4784a4701408d992e09/kawasakirb/20140827_sphinx2.md

1. SIerでもSphinxを使いた
い！ 後編
2014/08/27 kawasaki.rb #15
@kk_Ataka

2. 自己紹介
4 Twitter: @kk_Ataka
4 GitHub: gosyujin

3. 前編のあらすじ

4. 前編のあらすじ
4 Sphinxというドキュメンテーションツールを使いたい
4 導入するための理由づけ(政治)のために競合ツールと比較
4 Office(Word, Excel)
4 Wiki, Markdown
4 結果、初期導入にかかる手間以外は有用そう！
詳しくはkwskrb #13の資料参照

5. 今日やらないこと
4 Sphinxとはなんぞや
4 競合ツールとの比較

6. アジェンダ
4 Sphinxとは(前編でやった)
4 さらっと
4 競合ツールとの比較(前編でやった)
4 導入のためのあれこれ
4 導入した後どうするか

7. 導入するための壁
1. 対プロジェクトメンバー(PM)に対して
2. 対顧客に対して

8. 壁1. 対PM

9. 対PM 登場人物
4 自分
4 Sphinxを導入したい人、基本的になんでもやる
4 メンバー
4 導入したSphinxを使ってほしい人
4 油断するとすぐOfficeで日付バージョン管理@共有サー
バする

10. 対PM 「自分」の仕事
4 今回はreSTで進めることの明確な宣言
4 一番大事これができないと負の成果物が生成される…
4 メンバーが「特定のrstファイルを開いてドキュメント作
成」に注力できる環境を作る
4 sphinx-quickstartで下準備
4 ドキュメント自体のアウトライン作成
4 doctreeの作成

11. 対PM 「自分」の仕事
4 あわせてビルド環境、デプロイ環境などもお膳立て
4 ビルドはJenkinsで拾う
4 デプロイはApacheにhtmlファイル配備だろうか

12. 対PM 「メンバー」の仕事
4 reST記法を覚えてもらう
4 Markdownならなんとか…って場合はMarkdown ->
reSTという技もあるにはある
4 バージョン管理ツールは使えてください…

13. 対PM 課題
4 ローカルPCでのプレビュー
4 Python, Sphinxを入れてもらうのは厳しい
4 確認できるのがサーバにプッシュした時
4 ローカルでreSTプレビューできないだろうか…
4 GitHubだとできるんだけど

14. 対PM 課題
4 プロジェクト(会社)の風土にあわせたカスタマイズが必要
かもしれない
4 「変更履歴」出力プラグイン作ってみた

15. 壁2. 対顧客

16. 対顧客 登場人物
4 プロジェクト
4 我々側。Sphinxでドキュメント納品します
4 顧客
4 ドキュメントを納品される側
4 社内の人 or 社外の人
4 歴史的経緯からOfficeで納品される事が多い
4 例外はJavadocくらい？

17. 対顧客 「プロジェクト」の仕事
4 Sphinxで作成するドキュメントに関して「今回はOfficeじ
ゃない形式でドキュメント書きますよ」の合意を得とく

18. 対顧客 「顧客」の仕事
4 特になし？

19. 対顧客 課題
4 納品形式 最重要(次ページ参照)
4 納品後誰が保守するのかが大事
4 顧客が巻取ってしまう場合、どうしたらよいか
4 今のところ、納品対象外となっているドキュメントだ
けSphinxを使うという方針しかない？
4 要解決事項、誰かどうやってるか教えてください…

21. 色々考えた上で臨んだPJ

22. 現状
4 デモシステムのためドキュメントから何からすべて一任
4 紆余曲折があり開発担当が自分ほぼ一人になってしまった
(リーダー的な人とかは別にいる)
4 やりたい放題ランド
4 社内テンプレート( )仕込まれる前に前倒しでドキュメ
ント作りまくり

23. 現状
4 バージョン管理、差分管理もできて快適
4 軽い(普通のエディタで編集してるから)
4 意外と営業の人に受けが良かった
4 「え？なにこれ？なんてツール？あとで教えて」

24. 現状
4 Sphinx導入はできたが、思い描いていた事は実践できず…
4 ほぼ一人プロジェクトなので
4 しかし、ドキュメント開発スピードなどは加速できてい
る！(まったく定量的でない評価)
4 Office特有のもっさり感なし！
4 履歴管理など気にする必要なし！

25. 結論
4 プロジェクト全体でドキュメントをSphinxで書いていく！
空気を作るのが難しい
4 一人くらい好意的な「仲間」がいるとやりやすい
4 メンバーにreSTを強いるのが難しい
4 せめてmarkdownを書いたことがあれば敷居は低くなる
のに…
4 ドキュメントを書くスピードは爆速(個人的に！)