SIerでもSphinxを使いたい!総括

10,597 views

Published on

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

Published in: Technology
  • Be the first to comment

SIerでもSphinxを使いたい!総括

  1. 1. SIerでもSphinxを使いた い! 総括 2014/10/26 SphinxCon JP 2014 @kk_Ataka
  2. 2. 自己紹介 4 Twitter: @kk_Ataka 4 GitHub: gosyujin 4 普段いるところ 4 Kawasaki.rb 4 Jekyllrb-ja(主催) 4 Python力 4 文法もまだあやしい
  3. 3. 発表の趣旨 4 SIerでもSphinxを使いたいので職場で奮闘してみた備忘録 4 利用事例 4 拡張の紹介 4 Kawasaki.rbというイベントで話した内容の総集編 4 できたこと、できなかったこと含めて駆け足で共有します 4 主観が多め
  4. 4. 今日話さないこと 4 Sphinxとはなんぞや 4 reST記法とはなんぞや 4 Sphinxのインストール方法とか使い方とか
  5. 5. アジェンダ 1. 競合ツールとの比較 2. 導入のためのあれこれ、または導入後の課題 3. 実際に導入してみた感想
  6. 6. 競合ツールとの比較
  7. 7. 競合ツールとの比較! 4 導入するためには上の人を説得するための政治が必要… 4 競合ツールと比較してよさ気と思ったことを伝えていく 1. Office(Word, Excel) 2. Wiki, Markdown 3. Sphinx 4 好きな言葉「適材適所」
  8. 8. 比較1 Office
  9. 9. Office 長所 4 SI界のスタンダード 4 WYSIWYGな操作 4 きめ細かいデザインが可能 4 図やフローの挿入が容易 4 誰のPCにも入っていて、誰でも使える
  10. 10. !?
  11. 11. Office 短所 4 あらゆるものがOfficeで作成され、至る所にちらかる 4 日付バージョン管理…(主観) 4 恐怖の「 議事録_20140505_2(最新)(xx修正).xls 」 4 検索性が非常に悪い 4 違うシートとか、吹出しとか 非表示とか…探せない…
  12. 12. Office 短所 4 diffが取るのがメンドくさい 4 取れないとは言ってない、最近は取れるっぽい 4 ミリ単位のレイアウト修正を強いられる 4 リストとかすぐ壊れる 4 内容を集中して書かせて! 4 (職人芸が発揮されるほど)重い
  13. 13. 番外 Officeのいいところ…カット!
  14. 14. Officeのいいところ 4 Officeでしかできないことも、ある 4 過去資料でいいところあげてます! 4 ようは適材適所でよろしくお願いします
  15. 15. 比較2 Wiki, Markdown と Sphinx
  16. 16. Wiki, Markdown と Sphinx の長所 Officeで短所として挙げた問題は解消できている!…と思う
  17. 17. Wiki, Markdown と Sphinx の長所 > あらゆるものがOfficeで作成され、至る所にちらかる 問題 4 プレーンテキストで作成される 4 Officeよりは探しやすいんじゃないかと思うのだが… 4 ブラウザ、エディタの検索とか、Wiki内検索とか
  18. 18. Wiki, Markdown と Sphinx の長所 > diffが取るのがメンドくさい 問題 4 Markdownはプレーンテキストなので簡単 4 バージョン管理もしやすい 4 Wikiもだいたい差分表示機能あり 4 diff取りやすい
  19. 19. Wiki, Markdown と Sphinx の長所 > ミリ単位のレイアウト修正 問題 4 出力先(html+css、pdfなど)である程度統一できる
  20. 20. Wiki, Markdown と Sphinx の短所 Officeでは特に意識していなかったことを考慮する必要あり
  21. 21. Wiki, Markdown と Sphinx の短所 4 記法を覚える必要がある 4 未経験者にちょい敷居が高い… 4 「特定部分のみ」のレイアウト修正 4 cssなどに独自の処理を入れなければならない 4 図やフローの挿入はタグで挿入 4 直感的にいじれない(現物をD&D…)
  22. 22. Wiki, Markdown の短所 4 検索性はあまりよくない 4 しっかり作れば… 4 それでもOffice + 共有サーバコンボよりは… 4 重い 4 体感としては Office > Wiki, Markdown > Sphinx 4 サーバ性能とか同時アクセス数によるけど
  23. 23. Sphinx だけの長所 4 体系的なドキュメントの骨組みを簡単に整えられる 強力な 機能がある 4 この辺をサクッとよろしくやってくれているのが doctree...である気がする(まだ未調査) 4 Wikiとかでこれを整備するのはちょっとしんどい
  24. 24. Sphinx だけの長所 4 検索性はよいと思う 4 体系的にまとまるため 4 軽い 4 Outputが静的ファイル 4 htmlをWebサーバに置けば静的ファイルを取ってくるの と変わらない
  25. 25. ここまでのまとめ 4 慣れ親しんだOfficeから脱却したい、管理しやすい形式で ドキュメント作成に挑戦してみよう 4 ならば Wiki, Markdown か Sphinx だ! 4 TipsとかならWiki, Markdownでもいいけど、ドキュメン トなのである程度体系的に管理したい 4 体系的に管理するのが得意な Sphinx だ! 結論: 一回Sphinxチャレンジしてみましょう!
  26. 26. 導入のためのあれこれ、 または導入後の課題
  27. 27. 導入するための壁 1. 対プロジェクトメンバー(PM)に対して(布教) 2. 対顧客に対して(納品)
  28. 28. 壁1. 対PM
  29. 29. 対PM 登場人物 4 自分 4 Sphinxを導入したい人、基本的になんでもやる 4 メンバー 4 導入したSphinxを使ってほしい人
  30. 30. 対PM 「自分」の仕事 4 今回はreSTで進めることの明確な宣言とサポート 4 一番大事 4 これができないと負の成果物が生成される…
  31. 31. 対PM 「自分」の仕事 4 メンバーが「rstファイルを開いてドキュメント作成」に注 力できる環境を作る 1. sphinx-quickstartで下準備 2. ドキュメント自体のアウトライン作成 3. doctreeの作成 などなど
  32. 32. 対PM 「自分」の仕事 4 ビルド環境、デプロイ環境などもお膳立て 4 ビルドはJenkinsなどで拾う 4 デプロイはApacheにhtmlファイル配備とか(お手軽)
  33. 33. 対PM 「メンバー」の仕事 4 reST記法を覚えてもらう 4 Markdown -> reST -> Outputという裏技もある (Pandoc経由) 4 バージョン管理ツールとかの話は…割愛
  34. 34. 対PM 課題 4 ローカルPCでのプレビュー 4 メンバーのPCにSphinxを入れてもらうのは厳しい… 4 そうすると、確認できるのがサーバにプッシュした時の みになってしまう 4 ローカルで簡単にreSTプレビューできないだろうか… 4 GitHubとか使えばある程度できるんだけど
  35. 35. 対PM 課題 4 プロジェクト(会社)の風土にあわせたカスタマイズが必要 かも 4 こういうレイアウトがいい 4 こういうヘッダフッタがほしい 4 こういう改訂履歴ページがほしい
  36. 36. 対PM 課題 4 今回は「変更履歴」出力プラグイン作ってみた 4 sphinxcontrib-releasenotesプラグイン 4 .. releasenotes:: ディレクティブを追加したところにGit のコミットログと差分を貼り付け 4 Git使えない人用
  37. 37. 壁2. 対顧客
  38. 38. 対顧客 登場人物 4 プロジェクト 4 Sphinxでドキュメント納品する側 4 顧客 (社内の人 or 社外の人) 4 ドキュメントを納品される側 4 歴史的経緯からOfficeで納品される事が多い 4 例外はJavadocとか?
  39. 39. 対顧客 「プロジェクト」側の仕事 4 Sphinxで作成するドキュメントに関して「今回はOfficeじ ゃない形式で設計書とか書きますよ」の合意を得とく
  40. 40. 対顧客 「顧客」側の仕事 4 特になし?心構えくらい?
  41. 41. 対顧客 課題 4 納品形式 最重要(次ページ参照) 4 納品後 「誰が」 保守するのか 4 顧客が巻取ってしまう場合、どう保守すればよいのか 4 要解決事項、誰かどうやってるか教えてください… 4 これが解決できないと、Sphinxは納品対象外ドキュ メントにしか適用できない…
  42. 42. 実際に導入してみた感想
  43. 43. 環境 4 3ヶ月位のほぼ1人プロジェクトで「社内資料」をSphinx! 4 社内資料なので、納品関係の課題はスルー 4 環境揃えたい放題 4 Git + Sphinx + Jenkins etc 4 途中で1人サポートに入ってもらった
  44. 44. 結果 4 Gitでバージョン管理、テキストなので差分管理も簡単! 4 エディタが軽いので作成が快適! 4 Outputからお目当ての章が見やすい!探しやすい! 4 Outputは、意外と営業の人に受けが良かった! 4 「え?なにこれ?なんてツール?あとで教えて」
  45. 45. 結論 4 競合ツールとの比較 4 ドキュメントを書くスピードは早いよ! 4 導入のためのあれこれ、または導入後の課題 4 「Sphinxで書いていく!」空気を作るのが難しい 4 個人的には、「仲間(賛同者)」がいてくれると助かる
  46. 46. 結論 4 メンバーにreSTを書いてもらうのが難しい 4 メリットの周知、慣例からの脱却までが長い 4 納品物にするにはちょっと課題が多いかも 4 今回解決の糸口は見つからず…

×