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