Download as PDF, PPTX
Uploaded bykk_Ataka
JUS関西 Sphinxワークショップ@関西 Sphinx事例紹介
2015/10/31に開催されたSphinxワークショップ@関西(https://japanunixsociety.doorkeeper.jp/events/32899)の発表資料です。
JUS関西 Sphinxワークショップ@関西 Sphinx事例紹介
- 1.
- 2. 自己紹介 4 Twitter: @kk_Ataka 4GitHub: gosyujin 4 SIer勤務 4 Sphinxはプライベート で利用しつつ、仕事に も組み込めないか試行 錯誤中 ©2015 @kk_Ataka 2
- 3. アジェンダ 1. Sphinx導入前 4 導入のための政治活動 2.Sphinx導入中、導入した後 4 導入するにあたっての壁 4 「納品」するには 3. Sphinx導入事例 ©2015 @kk_Ataka 3
- 4.
- 5. はじめに 4 Sphinx(reST)の知名度調査 4 知名度0！ 4Markdownもあんまり 4 Wikiはかろうじて多少知られている まずは政治から ©2015 @kk_Ataka 5
- 6. 競合ツールと比較！ 4 競合ツールと比較しての良さを調査 1. Office(Word,Excel) 2. Wiki, Markdown ※ MarkdownはJekyllやHugoなどMarkdownで 記述できる静的サイトジェネレータを想定してい ます ©2015 @kk_Ataka 6
- 7.
- 8. Office 長所 Word,Excel共通 4 SI界のスタンダード 4 WYSIWYGな操作 4 きめ細かいデザインが可能 4 図やフローの挿入が容易 ©2015 @kk_Ataka 8
- 9. Office 長所 特にWord 4ものすごく複雑な箇条書きが簡単(？)に作れる 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
- 10. Office 長所 特にExcel 4エグい表/テーブルが簡単(？)に作れる 4 連結、結合たくさんあるマトリクスのような ものとか 4 Excel方眼紙フォーマット で自由自在(泣) 4 値の計算が簡単 4 これは表計算ソフトExcelの独壇場 4 表計算の用途にExcelを使うのは賛成 ©2015 @kk_Ataka 10
- 11. Office 短所 Word,Excel共通 4 diffが取るのがメンドくさい 4 最近は取れるっぽい 4 往々にして日付でバージョン管理される事 が多い 4 VCSと相性悪し 4 議事録_20140505_2(最新)(xx修正).xls ©2015 @kk_Ataka 11
- 12. Office 短所 Word,Excel共通 4 検索しづらい 4 違うシート / 吹出し / 非表示とか 4 ミリ単位のレイアウト修正を強いられる 4 大事なのは内容…そうでしょ！ 4 職人芸が発揮されるほど重い 4 1GBオーバーのファイル… ©2015 @kk_Ataka 12
- 13.
- 14. Wiki, Markdownの長所 4 Officeの短所は解消できている！…と思う ©2015@kk_Ataka 14
- 15. Wiki, Markdownの長所 "diffが取るのがメンドくさい" 4 Markdownはプレーンテキストなので簡単 4バージョン管理もしやすい 4 Wikiもだいたい差分表示機能あり 4 diff取りやすい ©2015 @kk_Ataka 15
- 16. Wiki, Markdownの長所 "検索しづらい" 4 Officeよりは探しやすいと思うのだが… 4ブラウザ、エディタの検索機能とか、Wiki 内検索とかを駆使して ©2015 @kk_Ataka 16
- 17.
- 18.
- 19. Wiki, Markdownの短所 4 記法を覚える必要がある 4未経験者に敷居が高い… 4 図やフローは基本的にタグで挿入 4 「特定部分のみ」のレイアウト修正が面倒 4 独自の処理を入れる？面倒… ©2015 @kk_Ataka 19
- 20. Wiki, Markdownの短所 4 しっかり作らないと情報が散らかる 4いわゆるTips集になってしまう 4 方言が多い(特にMarkdown) 4 PHP Markdown Extra, GitHub Flavored Markdown etc... 4 パーサが異なると出力結果が変わってしまう 4 逆に考えると表現方法が増えるため長所になり得る 4 出力はhtmlを想定しているものが多い ©2015 @kk_Ataka 20
- 21.
- 22. Sphinxの長所 4 Wiki, Markdownの長所と短所はだいたい Sphinxにも当てはまる 4Sphinxが強いところは… ©2015 @kk_Ataka 22
- 23. Sphinxの長所 4 体系的なドキュメント の骨組み を簡単に 整えられる 4 これだけで導入する価値あり 4 章の組み換え等も簡単 4 Wikiとかでこれを整備す るのはちょっとしんどい 4 Office(Word)はちょっと 得意かも 4 実際に作ってみないと実感が わきづらいと思う ©2015 @kk_Ataka 23
- 24. Sphinxの長所 4 複数ページをまたぐのも得意 4 索引ページ、用語集ページの作成も簡単 4html以外にも出力形式が豊富 4 text, pdf, epub, etc... ©2015 @kk_Ataka 24
- 25.
- 26.
- 27.
- 28.
- 29. 1. 対、プロジェクトのメンバー(PM)に対して 4 布教 2.対、顧客に対して 4 納品 ©2015 @kk_Ataka 29
- 30.
- 31. 対PM 登場人物 1. 自分 4Sphinxを導入したい 人、基本的になんでもや る 2. プロジェクトのメンバー (PM) 4 導入したSphinxを使っ てほしい人 ©2015 @kk_Ataka 31
- 32. 対PM 「自分」の仕事 4 「ドキュメントはreSTで作る」明確な宣言 4 一番大事 4 これがうまく周知されてないと負の成果物 が生成される… ©2015 @kk_Ataka 32
- 33. 対PM 「自分」の仕事 4 メンバーのサポート 4「ドキュメント作成するだけ」環境を作る 1. sphinx-quickstartで下準備 2. ドキュメント自体のアウトライン作成 3. doctreeの作成 などなど ©2015 @kk_Ataka 33
- 34. 対PM 「自分」の仕事 4 ビルド環境、デプロイ環境などもお膳立て 4ビルドはJenkinsなどで拾う 4 デプロイはWebサーバにhtmlファイル配備 とかがお手軽 4 commitすれば成果物が生成される事を周知 ©2015 @kk_Ataka 34
- 35. 対PM 「メンバー」の仕事 4 reST記法を覚えてもらう 負担を減らす ©2015@kk_Ataka 35
- 36. 対PM 課題 4 ローカルPCでのプレビューができない 4メンバーのPCにSphinxを入れてもらうのは厳 しい… 4 確認できるのがcommitした時のみになっ てしまう 4 ローカルで簡単にreSTプレビューできない 4 GitHubとか使えばある程度できるんだけど ©2015 @kk_Ataka 36
- 37. 対PM 課題 4 プロジェクトの風土にあわせたカスタマイズが 必要な場合も 4こういうレイアウトがいい 4 こういうヘッダフッタがほしい 4 社風にあわせて ©2015 @kk_Ataka 37
- 38.
- 39. 対顧客 登場人 物 1. プロジェクト 4Sphinxでドキュメント納品す る側 2. 顧客 4 ドキュメントを納品される側 4 社内の人 or 社外の人 4 歴史的経緯からOfficeで納品 される事が多い 4 例外はJavadocとか？ ©2015 @kk_Ataka 39
- 40. 対顧客 「プロジェクト」側 の仕事 4 顧客に対して宣言&合意を得る 4「今回はOfficeじゃない形式で設計書書き ますよ」 ©2015 @kk_Ataka 40
- 41. 対顧客 「顧客」側の仕事 4 特になし？心構えくらい？ ©2015@kk_Ataka 41
- 42. 対顧客 課題 4 納品形式(次ページ参照) 4 納品後 「誰が」 保守するのか 4 顧客が巻取ってしまう場合、どう保守すれ ばよいのか 4 要解決事項 4 これが解決できないと導入できない ©2015 @kk_Ataka 42
- 43.
- 44.
- 45.
- 46.
- 47. 環境 4 3ヶ月位のプロジェクトでSphinxを適用 4 ほぼ1人で設計、製造、テストを担当 4途中で1人サポートに入ってもらった 4 ドキュメント作成環境は Sphinx + Git(VCS) + Jenkins(Build) 4 ターゲットは「社内資料」 4 顧客へ納品しない資料 ©2015 @kk_Ataka 47
- 48. 導入した感想 1. Gitでバージョン管理、テキストなので差分管 理も簡単！ 2. 内容に集中できる！ 3.お目当ての章が見やすい！探しやすい！ 4. Outputは、意外と営業の人に受けが良かっ た！ 4 「これなんてツール？あとで教えて」 ©2015 @kk_Ataka 48
- 49. まとめ 1. 「Sphinxで書いていく！」空気を作るのが難 しい 4 reSTで文章を書いてもらうのも難しい 4「仲間」を作ろう！ 2. 「納品」するには課題もある 4 お客さんも巻き込もう！ ©2015 @kk_Ataka 49