2014/10/26 SphinxConJP 2014発表用資料です。

1. SIerでもSphinxを使いた
い！ 総括
2014/10/26 SphinxCon JP 2014
@kk_Ataka

2. 自己紹介
4 Twitter: @kk_Ataka
4 GitHub: gosyujin
4 普段いるところ
4 Kawasaki.rb
4 Jekyllrb-ja(主催)
4 Python力
4 文法もまだあやしい

3. 発表の趣旨
4 SIerでもSphinxを使いたいので職場で奮闘してみた備忘録
4 利用事例
4 拡張の紹介
4 Kawasaki.rbというイベントで話した内容の総集編
4 できたこと、できなかったこと含めて駆け足で共有します
4 主観が多め

4. 今日話さないこと
4 Sphinxとはなんぞや
4 reST記法とはなんぞや
4 Sphinxのインストール方法とか使い方とか

5. アジェンダ
1. 競合ツールとの比較
2. 導入のためのあれこれ、または導入後の課題
3. 実際に導入してみた感想

6. 競合ツールとの比較

7. 競合ツールとの比較！
4 導入するためには上の人を説得するための政治が必要…
4 競合ツールと比較してよさ気と思ったことを伝えていく
1. Office(Word, Excel)
2. Wiki, Markdown
3. Sphinx
4 好きな言葉「適材適所」

8. 比較1 Office

9. Office 長所
4 SI界のスタンダード
4 WYSIWYGな操作
4 きめ細かいデザインが可能
4 図やフローの挿入が容易
4 誰のPCにも入っていて、誰でも使える

10. !?

11. Office 短所
4 あらゆるものがOfficeで作成され、至る所にちらかる
4 日付バージョン管理…(主観)
4 恐怖の「 議事録_20140505_2(最新)(xx修正).xls 」
4 検索性が非常に悪い
4 違うシートとか、吹出しとか 非表示とか…探せない…

12. Office 短所
4 diffが取るのがメンドくさい
4 取れないとは言ってない、最近は取れるっぽい
4 ミリ単位のレイアウト修正を強いられる
4 リストとかすぐ壊れる
4 内容を集中して書かせて！
4 (職人芸が発揮されるほど)重い

13. 番外
Officeのいいところ…カット！

14. Officeのいいところ
4 Officeでしかできないことも、ある
4 過去資料でいいところあげてます！
4 ようは適材適所でよろしくお願いします

15. 比較2 Wiki, Markdown と
Sphinx

16. Wiki, Markdown と Sphinx の長所
Officeで短所として挙げた問題は解消できている！…と思う

17. Wiki, Markdown と Sphinx の長所
> あらゆるものがOfficeで作成され、至る所にちらかる 問題
4 プレーンテキストで作成される
4 Officeよりは探しやすいんじゃないかと思うのだが…
4 ブラウザ、エディタの検索とか、Wiki内検索とか

18. Wiki, Markdown と Sphinx の長所
> diffが取るのがメンドくさい 問題
4 Markdownはプレーンテキストなので簡単
4 バージョン管理もしやすい
4 Wikiもだいたい差分表示機能あり
4 diff取りやすい

19. Wiki, Markdown と Sphinx の長所
> ミリ単位のレイアウト修正 問題
4 出力先(html+css、pdfなど)である程度統一できる

20. Wiki, Markdown と Sphinx の短所
Officeでは特に意識していなかったことを考慮する必要あり

21. Wiki, Markdown と Sphinx の短所
4 記法を覚える必要がある
4 未経験者にちょい敷居が高い…
4 「特定部分のみ」のレイアウト修正
4 cssなどに独自の処理を入れなければならない
4 図やフローの挿入はタグで挿入
4 直感的にいじれない(現物をD&D…)

22. Wiki, Markdown の短所
4 検索性はあまりよくない
4 しっかり作れば…
4 それでもOffice + 共有サーバコンボよりは…
4 重い
4 体感としては Office > Wiki, Markdown > Sphinx
4 サーバ性能とか同時アクセス数によるけど

23. Sphinx だけの長所
4 体系的なドキュメントの骨組みを簡単に整えられる 強力な
機能がある
4 この辺をサクッとよろしくやってくれているのが
doctree...である気がする(まだ未調査)
4 Wikiとかでこれを整備するのはちょっとしんどい

24. Sphinx だけの長所
4 検索性はよいと思う
4 体系的にまとまるため
4 軽い
4 Outputが静的ファイル
4 htmlをWebサーバに置けば静的ファイルを取ってくるの
と変わらない

25. ここまでのまとめ
4 慣れ親しんだOfficeから脱却したい、管理しやすい形式で
ドキュメント作成に挑戦してみよう
4 ならば Wiki, Markdown か Sphinx だ！
4 TipsとかならWiki, Markdownでもいいけど、ドキュメン
トなのである程度体系的に管理したい
4 体系的に管理するのが得意な Sphinx だ！
結論: 一回Sphinxチャレンジしてみましょう！

26. 導入のためのあれこれ、
または導入後の課題

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

28. 壁1. 対PM

29. 対PM 登場人物
4 自分
4 Sphinxを導入したい人、基本的になんでもやる
4 メンバー
4 導入したSphinxを使ってほしい人

30. 対PM 「自分」の仕事
4 今回はreSTで進めることの明確な宣言とサポート
4 一番大事
4 これができないと負の成果物が生成される…

31. 対PM 「自分」の仕事
4 メンバーが「rstファイルを開いてドキュメント作成」に注
力できる環境を作る
1. sphinx-quickstartで下準備
2. ドキュメント自体のアウトライン作成
3. doctreeの作成
などなど

32. 対PM 「自分」の仕事
4 ビルド環境、デプロイ環境などもお膳立て
4 ビルドはJenkinsなどで拾う
4 デプロイはApacheにhtmlファイル配備とか(お手軽)

33. 対PM 「メンバー」の仕事
4 reST記法を覚えてもらう
4 Markdown -> reST -> Outputという裏技もある
(Pandoc経由)
4 バージョン管理ツールとかの話は…割愛

34. 対PM 課題
4 ローカルPCでのプレビュー
4 メンバーのPCにSphinxを入れてもらうのは厳しい…
4 そうすると、確認できるのがサーバにプッシュした時の
みになってしまう
4 ローカルで簡単にreSTプレビューできないだろうか…
4 GitHubとか使えばある程度できるんだけど

35. 対PM 課題
4 プロジェクト(会社)の風土にあわせたカスタマイズが必要
かも
4 こういうレイアウトがいい
4 こういうヘッダフッタがほしい
4 こういう改訂履歴ページがほしい

36. 対PM 課題
4 今回は「変更履歴」出力プラグイン作ってみた
4 sphinxcontrib-releasenotesプラグイン
4 .. releasenotes:: ディレクティブを追加したところにGit
のコミットログと差分を貼り付け
4 Git使えない人用

40. 壁2. 対顧客

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

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

43. 対顧客 「顧客」側の仕事
4 特になし？心構えくらい？

44. 対顧客 課題
4 納品形式 最重要(次ページ参照)
4 納品後 「誰が」 保守するのか
4 顧客が巻取ってしまう場合、どう保守すればよいのか
4 要解決事項、誰かどうやってるか教えてください…
4 これが解決できないと、Sphinxは納品対象外ドキュ
メントにしか適用できない…

46. 実際に導入してみた感想

47. 環境
4 3ヶ月位のほぼ1人プロジェクトで「社内資料」をSphinx！
4 社内資料なので、納品関係の課題はスルー
4 環境揃えたい放題
4 Git + Sphinx + Jenkins etc
4 途中で1人サポートに入ってもらった

48. 結果
4 Gitでバージョン管理、テキストなので差分管理も簡単！
4 エディタが軽いので作成が快適！
4 Outputからお目当ての章が見やすい！探しやすい！
4 Outputは、意外と営業の人に受けが良かった！
4 「え？なにこれ？なんてツール？あとで教えて」

49. 結論
4 競合ツールとの比較
4 ドキュメントを書くスピードは早いよ！
4 導入のためのあれこれ、または導入後の課題
4 「Sphinxで書いていく！」空気を作るのが難しい
4 個人的には、「仲間(賛同者)」がいてくれると助かる

50. 結論
4 メンバーにreSTを書いてもらうのが難しい
4 メリットの周知、慣例からの脱却までが長い
4 納品物にするにはちょっと課題が多いかも
4 今回解決の糸口は見つからず…