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.
SIerでもSphinxを使いた
い! 後編
2014/08/27 kawasaki.rb #15
@kk_Ataka
自己紹介
4 Twitter: @kk_Ataka
4 GitHub: gosyujin
前編のあらすじ
前編のあらすじ
4 Sphinxというドキュメンテーションツールを使いたい
4 導入するための理由づけ(政治)のために競合ツールと比較
4 Office(Word, Excel)
4 Wiki, Markdown
4 結果、初期導入にかかる手間...
今日やらないこと
4 Sphinxとはなんぞや
4 競合ツールとの比較
アジェンダ
4 Sphinxとは(前編でやった)
4 さらっと
4 競合ツールとの比較(前編でやった)
4 導入のためのあれこれ
4 導入した後どうするか
導入するための壁
1. 対プロジェクトメンバー(PM)に対して
2. 対顧客に対して
壁1. 対PM
対PM 登場人物
4 自分
4 Sphinxを導入したい人、基本的になんでもやる
4 メンバー
4 導入したSphinxを使ってほしい人
4 油断するとすぐOfficeで日付バージョン管理@共有サー
バする
対PM 「自分」の仕事
4 今回はreSTで進めることの明確な宣言
4 一番大事これができないと負の成果物が生成される…
4 メンバーが「特定のrstファイルを開いてドキュメント作
成」に注力できる環境を作る
4 sphinx-quicksta...
対PM 「自分」の仕事
4 あわせてビルド環境、デプロイ環境などもお膳立て
4 ビルドはJenkinsで拾う
4 デプロイはApacheにhtmlファイル配備だろうか
対PM 「メンバー」の仕事
4 reST記法を覚えてもらう
4 Markdownならなんとか…って場合はMarkdown ->
reSTという技もあるにはある
4 バージョン管理ツールは使えてください…
対PM 課題
4 ローカルPCでのプレビュー
4 Python, Sphinxを入れてもらうのは厳しい
4 確認できるのがサーバにプッシュした時
4 ローカルでreSTプレビューできないだろうか…
4 GitHubだとできるんだけど
対PM 課題
4 プロジェクト(会社)の風土にあわせたカスタマイズが必要
かもしれない
4 「変更履歴」出力プラグイン作ってみた
壁2. 対顧客
対顧客 登場人物
4 プロジェクト
4 我々側。Sphinxでドキュメント納品します
4 顧客
4 ドキュメントを納品される側
4 社内の人 or 社外の人
4 歴史的経緯からOfficeで納品される事が多い
4 例外はJavadocくらい?
対顧客 「プロジェクト」の仕事
4 Sphinxで作成するドキュメントに関して「今回はOfficeじ
ゃない形式でドキュメント書きますよ」の合意を得とく
対顧客 「顧客」の仕事
4 特になし?
対顧客 課題
4 納品形式 最重要(次ページ参照)
4 納品後誰が保守するのかが大事
4 顧客が巻取ってしまう場合、どうしたらよいか
4 今のところ、納品対象外となっているドキュメントだ
けSphinxを使うという方針しかない?
4 要解決事項...
色々考えた上で臨んだPJ
現状
4 デモシステムのためドキュメントから何からすべて一任
4 紆余曲折があり開発担当が自分ほぼ一人になってしまった
(リーダー的な人とかは別にいる)
4 やりたい放題ランド
4 社内テンプレート( )仕込まれる前に前倒しでドキュメ
ント作り...
現状
4 バージョン管理、差分管理もできて快適
4 軽い(普通のエディタで編集してるから)
4 意外と営業の人に受けが良かった
4 「え?なにこれ?なんてツール?あとで教えて」
現状
4 Sphinx導入はできたが、思い描いていた事は実践できず…
4 ほぼ一人プロジェクトなので
4 しかし、ドキュメント開発スピードなどは加速できてい
る!(まったく定量的でない評価)
4 Office特有のもっさり感なし!
4 履歴管理...
結論
4 プロジェクト全体でドキュメントをSphinxで書いていく!
空気を作るのが難しい
4 一人くらい好意的な「仲間」がいるとやりやすい
4 メンバーにreSTを強いるのが難しい
4 せめてmarkdownを書いたことがあれば敷居は低くなる...
SIerでもSphinxを使いたい! 後編
Upcoming SlideShare
Loading in …5
×

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

3,170 views

Published on

前編でSphinxと競合ツールの比較をしたので
今回は実際にどうやって導入していくかを考えました。
refs https://github.com/gosyujin/slideshare/blob/6d5ba7ab36e4426a4239b4784a4701408d992e09/kawasakirb/20140827_sphinx2.md

Published in: Technology
  • Be the first to comment

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

  1. 1. SIerでもSphinxを使いた い! 後編 2014/08/27 kawasaki.rb #15 @kk_Ataka
  2. 2. 自己紹介 4 Twitter: @kk_Ataka 4 GitHub: gosyujin
  3. 3. 前編のあらすじ
  4. 4. 前編のあらすじ 4 Sphinxというドキュメンテーションツールを使いたい 4 導入するための理由づけ(政治)のために競合ツールと比較 4 Office(Word, Excel) 4 Wiki, Markdown 4 結果、初期導入にかかる手間以外は有用そう! 詳しくはkwskrb #13の資料参照
  5. 5. 今日やらないこと 4 Sphinxとはなんぞや 4 競合ツールとの比較
  6. 6. アジェンダ 4 Sphinxとは(前編でやった) 4 さらっと 4 競合ツールとの比較(前編でやった) 4 導入のためのあれこれ 4 導入した後どうするか
  7. 7. 導入するための壁 1. 対プロジェクトメンバー(PM)に対して 2. 対顧客に対して
  8. 8. 壁1. 対PM
  9. 9. 対PM 登場人物 4 自分 4 Sphinxを導入したい人、基本的になんでもやる 4 メンバー 4 導入したSphinxを使ってほしい人 4 油断するとすぐOfficeで日付バージョン管理@共有サー バする
  10. 10. 対PM 「自分」の仕事 4 今回はreSTで進めることの明確な宣言 4 一番大事これができないと負の成果物が生成される… 4 メンバーが「特定のrstファイルを開いてドキュメント作 成」に注力できる環境を作る 4 sphinx-quickstartで下準備 4 ドキュメント自体のアウトライン作成 4 doctreeの作成
  11. 11. 対PM 「自分」の仕事 4 あわせてビルド環境、デプロイ環境などもお膳立て 4 ビルドはJenkinsで拾う 4 デプロイはApacheにhtmlファイル配備だろうか
  12. 12. 対PM 「メンバー」の仕事 4 reST記法を覚えてもらう 4 Markdownならなんとか…って場合はMarkdown -> reSTという技もあるにはある 4 バージョン管理ツールは使えてください…
  13. 13. 対PM 課題 4 ローカルPCでのプレビュー 4 Python, Sphinxを入れてもらうのは厳しい 4 確認できるのがサーバにプッシュした時 4 ローカルでreSTプレビューできないだろうか… 4 GitHubだとできるんだけど
  14. 14. 対PM 課題 4 プロジェクト(会社)の風土にあわせたカスタマイズが必要 かもしれない 4 「変更履歴」出力プラグイン作ってみた
  15. 15. 壁2. 対顧客
  16. 16. 対顧客 登場人物 4 プロジェクト 4 我々側。Sphinxでドキュメント納品します 4 顧客 4 ドキュメントを納品される側 4 社内の人 or 社外の人 4 歴史的経緯からOfficeで納品される事が多い 4 例外はJavadocくらい?
  17. 17. 対顧客 「プロジェクト」の仕事 4 Sphinxで作成するドキュメントに関して「今回はOfficeじ ゃない形式でドキュメント書きますよ」の合意を得とく
  18. 18. 対顧客 「顧客」の仕事 4 特になし?
  19. 19. 対顧客 課題 4 納品形式 最重要(次ページ参照) 4 納品後誰が保守するのかが大事 4 顧客が巻取ってしまう場合、どうしたらよいか 4 今のところ、納品対象外となっているドキュメントだ けSphinxを使うという方針しかない? 4 要解決事項、誰かどうやってるか教えてください…
  20. 20. 色々考えた上で臨んだPJ
  21. 21. 現状 4 デモシステムのためドキュメントから何からすべて一任 4 紆余曲折があり開発担当が自分ほぼ一人になってしまった (リーダー的な人とかは別にいる) 4 やりたい放題ランド 4 社内テンプレート( )仕込まれる前に前倒しでドキュメ ント作りまくり
  22. 22. 現状 4 バージョン管理、差分管理もできて快適 4 軽い(普通のエディタで編集してるから) 4 意外と営業の人に受けが良かった 4 「え?なにこれ?なんてツール?あとで教えて」
  23. 23. 現状 4 Sphinx導入はできたが、思い描いていた事は実践できず… 4 ほぼ一人プロジェクトなので 4 しかし、ドキュメント開発スピードなどは加速できてい る!(まったく定量的でない評価) 4 Office特有のもっさり感なし! 4 履歴管理など気にする必要なし!
  24. 24. 結論 4 プロジェクト全体でドキュメントをSphinxで書いていく! 空気を作るのが難しい 4 一人くらい好意的な「仲間」がいるとやりやすい 4 メンバーにreSTを強いるのが難しい 4 せめてmarkdownを書いたことがあれば敷居は低くなる のに… 4 ドキュメントを書くスピードは爆速(個人的に!)

×