29
SIerでもSphinxを使いた い! 前編 2014/06/25 kawasaki.rb #13 @kk_Ataka

SIerでもSphinxを使いたい! 前編

  • Upload
    kkataka

  • View
    1.327

  • Download
    0

Embed Size (px)

DESCRIPTION

Sphinxを導入したいので、競合ツールと比較しました。 refs https://github.com/gosyujin/slideshare/commit/c6918bee7bc74bcd0dcfa91371214f6832086215

Citation preview

Page 1: SIerでもSphinxを使いたい! 前編

SIerでもSphinxを使いたい! 前編

2014/06/25 kawasaki.rb #13

@kk_Ataka

Page 2: SIerでもSphinxを使いたい! 前編

自己紹介4 Twitter: @kk_Ataka

4 GitHub: gosyujin

Page 3: SIerでもSphinxを使いたい! 前編

アジェンダ4 Sphinxとは4 さらっと

4 競合ツールとの比較4 導入のためのあれこれ(後編で)4 導入した後どうするか(後編で)

Page 4: SIerでもSphinxを使いたい! 前編

話さないこと4 SphinxやreSTの詳しい説明など4 「Sphinxを学ぼう」ではなく「Sphinxを導入するためにあれこれ考えた」事を話します

Page 5: SIerでもSphinxを使いたい! 前編

Sphinxとは(さらっと)4 「美しいドキュメントを簡単に生成することができるドキュメンテーションツール」(Sphinx-Users.jpより)

4 reSTという記法を使ってドキュメントを作成する4 Python製4 そのためかPython公式ドキュメントなどPython界隈での使用が盛ん

Page 6: SIerでもSphinxを使いたい! 前編

Sphinxを入れたい!4 導入するためには上の人を説得するための政治が必要…

4 競合ツールと比較してよさ気と思ったことを伝えていく4 Office(Word, Excel)

4 Wiki, Markdown

4 Sphinx

Page 7: SIerでもSphinxを使いたい! 前編

競合ツールとの比較

Page 8: SIerでもSphinxを使いたい! 前編

比較1 Office(Word, Excel)

Page 9: SIerでもSphinxを使いたい! 前編

Office 長所4 SI界のスタンダード4 WYSIWYGな操作4 きめ細かいデザインが可能4 図やフローの挿入が容易

4 誰のPCにも入っていて、誰でも使える (※ 一般論)

Page 10: SIerでもSphinxを使いたい! 前編

Office 短所4 あらゆるものがOfficeで作成され、共有サーバや添付ファイルにちらかる4 チームによる、しかしセットでくる傾向は非常に高い4 伝説の「 議事録_20140505_2(最新)(xx修正).xls 」

4 検索性が非常に悪い4 シート分かれてたり 吹出しに書かれてたり 非表示だったり

Page 11: SIerでもSphinxを使いたい! 前編

Office 短所4 diffが取るのがメンドくさい4 取れないとは言ってない

4 ミリ単位のレイアウト修正4 内容を集中して書かせて!

4 あと重い(※ 個人的に)

Page 12: SIerでもSphinxを使いたい! 前編

番外Officeのいいところ

Page 13: SIerでもSphinxを使いたい! 前編

Officeのいいところ4 ものすごく複雑な箇条書きが簡単(?)に作れる 1.1. 方針 1.2. スケジュール 1.2.1. テスト1

1.2.1.1. 詳細 #=> どこまで深く…

... #=> そこに文章色々書いて…

1.2.2. テスト2

1.3. 役割分担 #=> からの復帰とか

Page 14: SIerでもSphinxを使いたい! 前編

Officeのいいところ4 エグい表/テーブルが簡単(?)に作れる4 連結とかがすごいしてあるマトリクスのようなもの

4 値の計算(Excel)4 これはExcelの独壇場、さすがは表計算ソフト4 表計算の用途にExcelを使うのは賛成

適材適所が大事

Page 15: SIerでもSphinxを使いたい! 前編

比較2 Wiki, Markdown

Page 16: SIerでもSphinxを使いたい! 前編

Wiki, Markdown 長所Officeで短所として挙げた問題は解消できる > あらゆるものがOfficeで作成され、共有サーバや添付ファイルにちらかる

4 プレーンテキストで作成され、Wiki内などにちらかる4 一応、探すあてはある

Page 17: SIerでもSphinxを使いたい! 前編

Wiki, Markdown 長所 > diffが取るのがメンドくさい4 Markdownはプレーンテキストなので簡単4 Wikiもだいたい差分表示機能あり

Page 18: SIerでもSphinxを使いたい! 前編

Wiki, Markdown 長所 > ミリ単位のレイアウト修正4 出力先(htmlとcssなど)である程度統一できる4 アウトプットをブラウザで見ることを前提

Page 19: SIerでもSphinxを使いたい! 前編

Wiki, Markdown 長所加えて4 プレーンテキストなのでバージョン管理しやすい4 diff取りやすい

Page 20: SIerでもSphinxを使いたい! 前編

Wiki, Markdown 短所4 検索性はあまりよくない(気がする)

4 それでもOffice + 共有サーバコンボよりは…

4 重い4 ただしサーバ性能とか同時アクセス数とかにもよる

Page 21: SIerでもSphinxを使いたい! 前編

Wiki, Markdown 短所他に、Officeでできたことが一部短所に4 記法を覚える必要がある4 「特定部分のみ」のレイアウト修正4 cssなどに独自の処理を入れなければならない

4 図やフローの挿入はタグで挿入4 D&Dとかで現物を見ながら直感的にいじれない

Page 22: SIerでもSphinxを使いたい! 前編

比較3 Sphinx

Page 23: SIerでもSphinxを使いたい! 前編

Sphinx 長所Wiki, Markdownの長所は引き継げる。プラス4 Sphinxには 体系的なドキュメントの骨組みを整えられる 強力な機能がある4 この辺をうまくやってくれているのがdoctree

4 のような気がする(まだ未調査)

Page 24: SIerでもSphinxを使いたい! 前編

Sphinx 長所また、Wiki, Markdownでつらかったことは解消されている4 検索性はよい4 体系的にまとまるため

4 軽い4 アウトプットがhtml, pdfなど4 htmlをWebサーバに置けば静的ファイルを取ってくるのと変わらない

Page 25: SIerでもSphinxを使いたい! 前編

Sphinx 短所Wiki, Markdownと同様につらい4 記法を覚える必要がある4 「特定部分のみ」のレイアウト修正4 cssなどに独自の処理を入れなければならない

4 図やフローの挿入はタグで挿入4 D&Dとかで現物を見ながら直感的にいじれない

Page 26: SIerでもSphinxを使いたい! 前編

総評

Page 27: SIerでもSphinxを使いたい! 前編

総評4 慣れ親しんだOfficeから脱却し、管理しやすい形式でドキュメント作成に挑戦してみよう4 ならば Wiki, Markdown か Sphinx だ!

4 TipsとかならWiki, Markdownでもいいけど、ドキュメントなのである程度体系的に管理したい4 体系的に管理するのが得意な Sphinx だ!

Page 28: SIerでもSphinxを使いたい! 前編

結論Sphinxを使ってみる!

Page 29: SIerでもSphinxを使いたい! 前編

==後編に続く==>