Download to read offline
Uploaded bykk_Ataka
SIerでもSphinxを使いたい！ 前編
Sphinxを導入したいので、競合ツールと比較しました。 refs https://github.com/gosyujin/slideshare/commit/c6918bee7bc74bcd0dcfa91371214f6832086215
SIerでもSphinxを使いたい！ 前編
- 1. SIerでもSphinxを使いた い！ 前編 2014/06/25 kawasaki.rb#13 @kk_Ataka
- 2. 自己紹介 4 Twitter: @kk_Ataka 4GitHub: gosyujin
- 3. アジェンダ 4 Sphinxとは 4 さらっと 4競合ツールとの比較 4 導入のためのあれこれ(後編で) 4 導入した後どうするか(後編で)
- 4.
- 5. Sphinxとは(さらっと) 4 「美しいドキュメントを簡単に生成することができるドキ ュメンテーションツール」(Sphinx-Users.jpより) 4 reSTという記法を使ってドキュメントを作成する 4Python製 4 そのためかPython公式ドキュメントなどPython界隈で の使用が盛ん
- 6. Sphinxを入れたい！ 4 導入するためには上の人を説得するための政治が必要… 4 競合ツールと比較してよさ気と思ったことを伝えていく 4Office(Word, Excel) 4 Wiki, Markdown 4 Sphinx
- 7.
- 8.
- 9. Office 長所 4 SI界のスタンダード 4WYSIWYGな操作 4 きめ細かいデザインが可能 4 図やフローの挿入が容易 4 誰のPCにも入っていて、誰でも使える (※ 一般論)
- 10. Office 短所 4 あらゆるものがOfficeで作成され、共有サーバや添付ファ イルにちらかる 4チームによる、しかしセットでくる傾向は非常に高い 4 伝説の「 議事録_20140505_2(最新)(xx修正).xls 」 4 検索性が非常に悪い 4 シート分かれてたり 吹出しに書かれてたり 非表示だっ たり
- 11. Office 短所 4 diffが取るのがメンドくさい 4取れないとは言ってない 4 ミリ単位のレイアウト修正 4 内容を集中して書かせて！ 4 あと重い(※ 個人的に)
- 12.
- 13. Officeのいいところ 4 ものすごく複雑な箇条書きが簡単(？)に作れる 1.1. 方針 1.2.スケジュール 1.2.1. テスト1 1.2.1.1. 詳細 #=> どこまで深く… ... #=> そこに文章色々書いて… 1.2.2. テスト2 1.3. 役割分担 #=> からの復帰とか
- 14. Officeのいいところ 4 エグい表/テーブルが簡単(？)に作れる 4 連結とかがすごいしてあるマトリクスのようなもの 4値の計算(Excel) 4 これはExcelの独壇場、さすがは表計算ソフト 4 表計算の用途にExcelを使うのは賛成 適材適所が大事
- 15.
- 16. Wiki, Markdown 長所 Officeで短所として挙げた問題は解消できる >あらゆるものがOfficeで作成され、共有サーバや添付ファイルにちらかる 4 プレーンテキストで作成され、Wiki内などにちらかる 4 一応、探すあてはある
- 17. Wiki, Markdown 長所 >diffが取るのがメンドくさい 4 Markdownはプレーンテキストなので簡単 4 Wikiもだいたい差分表示機能あり
- 18. Wiki, Markdown 長所 >ミリ単位のレイアウト修正 4 出力先(htmlとcssなど)である程度統一できる 4 アウトプットをブラウザで見ることを前提
- 19. Wiki, Markdown 長所 加えて 4プレーンテキストなのでバージョン管理しやすい 4 diff取りやすい
- 20. Wiki, Markdown 短所 4検索性はあまりよくない(気がする) 4 それでもOffice + 共有サーバコンボよりは… 4 重い 4 ただしサーバ性能とか同時アクセス数とかにもよる
- 21. Wiki, Markdown 短所 他に、Officeでできたことが一部短所に 4記法を覚える必要がある 4 「特定部分のみ」のレイアウト修正 4 cssなどに独自の処理を入れなければならない 4 図やフローの挿入はタグで挿入 4 D&Dとかで現物を見ながら直感的にいじれない
- 22.
- 23. Sphinx 長所 Wiki, Markdownの長所は引き継げる。プラス 4Sphinxには 体系的なドキュメントの骨組みを整えられる 強力な機能がある 4 この辺をうまくやってくれているのがdoctree 4 のような気がする(まだ未調査)
- 24. Sphinx 長所 また、Wiki, Markdownでつらかったことは解消されている 4検索性はよい 4 体系的にまとまるため 4 軽い 4 アウトプットがhtml, pdfなど 4 htmlをWebサーバに置けば静的ファイルを取ってくるの と変わらない
- 25. Sphinx 短所 Wiki, Markdownと同様につらい 4記法を覚える必要がある 4 「特定部分のみ」のレイアウト修正 4 cssなどに独自の処理を入れなければならない 4 図やフローの挿入はタグで挿入 4 D&Dとかで現物を見ながら直感的にいじれない
- 26.
- 27. 総評 4 慣れ親しんだOfficeから脱却し、管理しやすい形式でドキ ュメント作成に挑戦してみよう 4 ならばWiki, Markdown か Sphinx だ！ 4 TipsとかならWiki, Markdownでもいいけど、ドキュメン トなのである程度体系的に管理したい 4 体系的に管理するのが得意な Sphinx だ！
- 28.
- 29.