厂滨别谤でも厂辫丑颈苍虫を使いたい！総括
- 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 (職人芸が発揮されるほど)重い
- 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チャレンジしてみましょう！
- 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 今回解決の糸口は見つからず…