Successfully reported this slideshow.

JUS関西 Sphinxワークショップ@関西 Sphinx事例紹介

4,342 views

Published on

2015/10/31に開催されたSphinxワークショップ@関西(https://japanunixsociety.doorkeeper.jp/events/32899)の発表資料です。

Published in: Technology
  • Be the first to comment

JUS関西 Sphinxワークショップ@関西 Sphinx事例紹介

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

×