SphinxCon JP 2015での発表資料

1. Sphinxで社内勉強会(Git)の
資料を作ってみた
清水 琢
(@takuan_osho)
SphinxCon JP 2015

2. 自己紹介
清水 琢 (@takuan_osho)
• 非IT系企業で社内システムのお守り
• いわゆる社内SE的な仕事をしている
• Sphinxとの関わり
• 初めて触れたのがSphinx翻訳ハッカソン(2011/2/12)
• 「翻訳」の部分に惹かれて初参加
• それから色々なコミュニティに参加するようになる

3. 話すこと
今回話したいことはだいたい以下の通り。
• 事例紹介
• (Sphinxを使った時の)社内勉強会資料作成の考え方
• 「何故この選択をしたか？」ということについて

4. 話さないこと
今回触れないことは以下の通り。
• Sphinxの機能紹介・深い使い方

5. 目次
• 社内資料を作ることになった経緯
• 資料作成で一番重要視したこと
• Sphinxを使おうと思った理由
• Sphinxを使ってよかったこと
• 上手くいかなかったこと
• まとめ

6. 目次
• 社内資料を作ることになった経緯
• 資料作成で一番重要視したこと
• Sphinxを使おうと思った理由
• Sphinxを使ってよかったこと
• 上手くいかなかったこと
• まとめ

7. 社内資料を作ることになった経緯
Gitが新しく導入される。
• 日付バージョン管理辛いので導入された。
• チームメンバーの大半が
Gitにそれほど精通していない
=> 社内勉強会の必要性
• 上司から勉強会用の資料を
作るように言われる。

8. 目次
• 社内資料を作ることになった経緯
• 資料作成で一番重要視したこと
• Sphinxを使おうと思った理由
• Sphinxを使ってよかったこと
• 上手くいかなかったこと
• まとめ

9. 資料作成で一番重要視したこと
「何を書くか？」ではなく
「何を書かないか？」を考えて資料を作成。

10. 理由
題材がGitだから
• 書こうと思えば書けることが多すぎる題材。

11. 資料を作る目的をはっきりさせる
• 資料を作ることで「何を達成したいか？」に注目。
• 「業務で何とかついていける下地を作る」ことを目指す。
=> 前提知識の記述に集中 (=運用に関することは省く)
• 振り返って見通せる量に抑えた説明
• CUIの基礎知識
• 必要最低限のコマンドの使い方
• (Gitの基本構造)

12. 実際の資料

13. 説明が足りないところについて
• 世にあるGit関連の分かりやすい資料を活用
• 勉強会中の実演・実際の業務・口頭などで補足

14. 目次
• 社内資料を作ることになった経緯
• 資料作成で一番重要視したこと
• Sphinxを使おうと思った理由
• Sphinxを使ってよかったこと
• 上手くいかなかったこと
• まとめ

15. Sphinxを使おうと思った理由
使い慣れていたことが最大の理由
以下の機能が有効活用できそうだと
アタリがついていた
• コマンドラインの記述が割と得意
• 見たままの感じ + コピペのしやすさ
• (メンテしやすい)コミットログの図を描く
• blockdiagを使用することを想定
• 完全に成功したとは言い難い

16. 目次
• 社内資料を作ることになった経緯
• 資料作成で一番重要視したこと
• Sphinxを使おうと思った理由
• Sphinxを使ってよかったこと
• 上手くいかなかったこと
• まとめ

17. Sphinxを使ってよかったこと
目次の自動生成
• 資料の提示順を変更しやすい
• 構造が固まりきっていない時は非常に有用
• 資料の入り口を示せば関連資料が全て見える
• (関連する資料に限り)散逸しづらい
• 章ごとにファイル分割して後でまとめても
自動で追従してくれる嬉しさ

18. 目次
• 社内資料を作ることになった経緯
• 資料作成で一番重要視したこと
• Sphinxを使おうと思った理由
• Sphinxを使ってよかったこと
• 上手くいかなかったこと
• まとめ

19. 上手くいかなかったこと
コミットログをblockdiagで無理矢理描いたこと
• 複雑でなければ描くのは可能
• しかし、メンテナンス性は悪い(と思う)

20. 生成した図

21. 生成した図のもとのコード
blockdiag {
default_group_color = lightgreen
default_fontsize = 15
default_shape = "circle"
remote_firstlabel"A"];
remote_secondlabel"B"];
remote_thirdlabel"C"];
remote_master_branchlabel"* master", shape"roundedbox",
colorpink;
local_firstlabel"A"];
local_secondlabel"B"];
local_thirdlabel"C"];
local_master_branchlabel"* master", shape"roundedbox",
colorpink;
group {
remote_first <- remote_second <- remote_third
remote_third <- remote_master_branchdirnone styledashed
}
group {
local_first <- local_second <- local_third
local_third <- local_master_branchdirnone styledashed
}
}

22. 生成した図

23. 生成した図のもとのコード
blockdiag {
default_group_color = lightgreen
default_fontsize = 15
default_shape = "circle"
remote_firstlabel"A"];
remote_secondlabel"B"];
remote_thirdlabel"C"];
remote_master_branchlabel"* master", shape"roundedbox", colorpink;
local_firstlabel"A"];
local_secondlabel"B"];
local_thirdlabel"C"];
local_fourthlabel"D", color"orange"];
local_new_branchlabel"* featureadd-test-site", shape"roundedbox",
colorpink;
local_before_new_branchlabel"featureadd-test-site", shape"roundedbox",
colorgray;
local_master_branchlabel"master", shape"roundedbox", colorpink;
group {
remote_first <- remote_second <- remote_third
remote_third <- remote_master_branchdirnone styledashed
}
group {
local_first <- local_second <- local_third <- local_fourth
local_fourth <- local_new_branchdirnone styledashed
local_third <- local_before_new_branchdirnone styledashed
local_third <- local_master_branchdirnone styledashed
local_before_new_branch -> local_new_branchthick color"red"]
}
}

24. 上手くいかなかったこと
メンテする機会を
無くしたつもりではあるけど
必要な時のメンテがつらい…

25. 上手くいかなかったこと
予想より各人のサポートする必要があったこと
• 資料+αの練習だけでは畳の上の水練でしかない

26. 目次
• 社内資料を作ることになった経緯
• 資料作成で一番重要視したこと
• Sphinxを使おうと思った理由
• Sphinxを使ってよかったこと
• 上手くいかなかったこと
• まとめ

27. まとめ
目的に合ったツール選択が重要
• Sphinxに拘らない
• メンテナンス性も考慮に入れる
資料は「書いたら終わり」ではない
• 書いた後のことも視野に入れた資料作りが大切

28. 質問