jus関西 sphinxワークショップ@関西 sphinx事例紹介

Sphinx事例紹介～SIerの場合～

2015/10/31JUS Sphinxワークショップ＠

関西©2015 @kk_Ataka 1

自己紹介4 Twitter: @kk_Ataka

4 GitHub: gosyujin

4 SIer勤務4 Sphinxはプライベートで利用しつつ、仕事にも組み込めないか試行錯誤中

©2015 @kk_Ataka 2

アジェンダ1. Sphinx導入前4 導入のための政治活動

2. Sphinx導入中、導入した後4 導入するにあたっての壁4 「納品」するには

3. Sphinx導入事例

©2015 @kk_Ataka 3

Sphinx導入前

©2015 @kk_Ataka 4

はじめに4 Sphinx(reST)の知名度調査4 知名度0！

4 Markdownもあんまり4 Wikiはかろうじて多少知られているまずは政治から

©2015 @kk_Ataka 5

競合ツールと比較！4 競合ツールと比較しての良さを調査

1. Office(Word, Excel)

2. Wiki, Markdown

※ MarkdownはJekyllやHugoなどMarkdownで記述できる静的サイトジェネレータを想定しています

©2015 @kk_Ataka 6

比較1Office(Word, Excel)

©2015 @kk_Ataka 7

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

©2015 @kk_Ataka 8

Office 長所特にWord4 ものすごく複雑な箇条書きが簡単(？)に作れる 1.1. 設計方針 1.2. 開発スケジュール 1.2.1. 要件定義 // => ネストしていく 1.2.1.1. xx機能 // => さらにネスト…

1.2.1.2. yy機能 // => 色々書いて…

1.2.2. 基本設計 // => ネストからの復帰 1.3. 開発体制 // => さらに復帰©2015 @kk_Ataka 9

Office 長所特にExcel4 エグい表/テーブルが簡単(？)に作れる4 連結、結合たくさんあるマトリクスのようなものとか

4 Excel方眼紙フォーマットで自由自在(泣)

4 値の計算が簡単4 これは表計算ソフトExcelの独壇場4 表計算の用途にExcelを使うのは賛成

©2015 @kk_Ataka 10

Office 短所 Word, Excel共通4 diffが取るのがメンドくさい4 最近は取れるっぽい4 往々にして日付でバージョン管理される事が多い4 VCSと相性悪し

4 議事録_20140505_2(最新)(xx修正).xls

©2015 @kk_Ataka 11

Office 短所 Word, Excel共通4 検索しづらい4 違うシート / 吹出し / 非表示とか

4 ミリ単位のレイアウト修正を強いられる4 大事なのは内容…そうでしょ！

4 職人芸が発揮されるほど重い4 1GBオーバーのファイル…

©2015 @kk_Ataka 12

比較2Wiki, Markdown

©2015 @kk_Ataka 13

Wiki, Markdownの長所4 Officeの短所は解消できている！…と思う

©2015 @kk_Ataka 14

Wiki, Markdownの長所"diffが取るのがメンドくさい"

4 Markdownはプレーンテキストなので簡単4 バージョン管理もしやすい

4 Wikiもだいたい差分表示機能あり4 diff取りやすい

©2015 @kk_Ataka 15

Wiki, Markdownの長所"検索しづらい"

4 Officeよりは探しやすいと思うのだが…4 ブラウザ、エディタの検索機能とか、Wiki内検索とかを駆使して

©2015 @kk_Ataka 16

Wiki, Markdownの長所"ミリ単位のレイアウト修正"

4 出力先(html+cssなど)である程度統一できる

©2015 @kk_Ataka 17

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

©2015 @kk_Ataka 18

Wiki, Markdownの短所4 記法を覚える必要がある4 未経験者に敷居が高い…4 図やフローは基本的にタグで挿入

4 「特定部分のみ」のレイアウト修正が面倒4 独自の処理を入れる？面倒…

©2015 @kk_Ataka 19

Wiki, Markdownの短所4 しっかり作らないと情報が散らかる4 いわゆるTips集になってしまう

4 方言が多い(特にMarkdown)

4 PHP Markdown Extra, GitHub Flavored Markdown etc...

4 パーサが異なると出力結果が変わってしまう4 逆に考えると表現方法が増えるため長所になり得る

4 出力はhtmlを想定しているものが多い©2015 @kk_Ataka 20

そしてSphinx

©2015 @kk_Ataka 21

Sphinxの長所4 Wiki, Markdownの長所と短所はだいたい

Sphinxにも当てはまる4 Sphinxが強いところは…

©2015 @kk_Ataka 22

Sphinxの長所4 体系的なドキュメントの骨組みを簡単に整えられる4 これだけで導入する価値あり4 章の組み換え等も簡単4 Wikiとかでこれを整備するのはちょっとしんどい

4 Office(Word)はちょっと得意かも

4 実際に作ってみないと実感がわきづらいと思う

©2015 @kk_Ataka 23

Sphinxの長所4 複数ページをまたぐのも得意4 索引ページ、用語集ページの作成も簡単

4 html以外にも出力形式が豊富4 text, pdf, epub, etc...

©2015 @kk_Ataka 24

索引ページ4 こんな感じ

©2015 @kk_Ataka 25

用語集ページ4 こんな感じ

©2015 @kk_Ataka 26

Sphinx導入中と

導入した後

©2015 @kk_Ataka 27

導入するにあたっての壁

©2015 @kk_Ataka 28

1. 対、プロジェクトのメンバー(PM)に対して4 布教

2. 対、顧客に対して4 納品

©2015 @kk_Ataka 29

壁1. 対PM

©2015 @kk_Ataka 30

対PM 登場人物1. 自分4 Sphinxを導入したい人、基本的になんでもやる

2. プロジェクトのメンバー(PM)

4 導入したSphinxを使ってほしい人

©2015 @kk_Ataka 31

対PM 「自分」の仕事4 「ドキュメントはreSTで作る」明確な宣言4 一番大事4 これがうまく周知されてないと負の成果物が生成される…

©2015 @kk_Ataka 32

対PM 「自分」の仕事4 メンバーのサポート4 「ドキュメント作成するだけ」環境を作る1. sphinx-quickstartで下準備2. ドキュメント自体のアウトライン作成3. doctreeの作成

などなど

©2015 @kk_Ataka 33

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

4 commitすれば成果物が生成される事を周知

©2015 @kk_Ataka 34

対PM 課題4 ローカルPCでのプレビューができない4 メンバーのPCにSphinxを入れてもらうのは厳しい…4 確認できるのがcommitした時のみになってしまう

4 ローカルで簡単にreSTプレビューできない4 GitHubとか使えばある程度できるんだけど

©2015 @kk_Ataka 36

対顧客登場人物1. プロジェクト4 Sphinxでドキュメント納品する側

2. 顧客4 ドキュメントを納品される側4 社内の人 or 社外の人

4 歴史的経緯からOfficeで納品される事が多い4 例外はJavadocとか？

©2015 @kk_Ataka 39

環境4 3ヶ月位のプロジェクトでSphinxを適用4 ほぼ1人で設計、製造、テストを担当4 途中で1人サポートに入ってもらった

4 ドキュメント作成環境は Sphinx + Git(VCS) + Jenkins(Build)

4 ターゲットは「社内資料」4 顧客へ納品しない資料

©2015 @kk_Ataka 47

導入した感想1. Gitでバージョン管理、テキストなので差分管理も簡単！

2. 内容に集中できる！3. お目当ての章が見やすい！探しやすい！4. Outputは、意外と営業の人に受けが良かった！4 「これなんてツール？あとで教えて」

©2015 @kk_Ataka 48

jus関西 sphinxワークショップ@関西 sphinx事例紹介

Technology