Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

5,107 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

×