Sphinxで社内勉強会(Git)の
資料を作ってみた

5,241 views

Published on

SphinxCon JP 2015での発表資料

Published in: Technology
0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
5,241
On SlideShare
0
From Embeds
0
Number of Embeds
2,859
Actions
Shares
0
Downloads
5
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide

Sphinxで社内勉強会(Git)の
資料を作ってみた

  1. 1. Sphinxで社内勉強会(Git)の
 資料を作ってみた 清水 琢 (@takuan_osho)
 
 SphinxCon JP 2015
  2. 2. 自己紹介 清水 琢 (@takuan_osho) • 非IT系企業で社内システムのお守り • いわゆる社内SE的な仕事をしている • Sphinxとの関わり • 初めて触れたのがSphinx翻訳ハッカソン(2011/2/12) • 「翻訳」の部分に惹かれて初参加 • それから色々なコミュニティに参加するようになる
  3. 3. 話すこと 今回話したいことはだいたい以下の通り。
 • 事例紹介
 • (Sphinxを使った時の)社内勉強会資料作成の考え方 • 「何故この選択をしたか?」ということについて
  4. 4. 話さないこと 今回触れないことは以下の通り。 
 • Sphinxの機能紹介・深い使い方
  5. 5. 目次 • 社内資料を作ることになった経緯 • 資料作成で一番重要視したこと • Sphinxを使おうと思った理由 • Sphinxを使ってよかったこと • 上手くいかなかったこと • まとめ
  6. 6. 目次 • 社内資料を作ることになった経緯 • 資料作成で一番重要視したこと • Sphinxを使おうと思った理由 • Sphinxを使ってよかったこと • 上手くいかなかったこと • まとめ
  7. 7. 社内資料を作ることになった経緯 Gitが新しく導入される。 • 日付バージョン管理辛いので導入された。 • チームメンバーの大半が
 Gitにそれほど精通していない => 社内勉強会の必要性 • 上司から勉強会用の資料を
 作るように言われる。
  8. 8. 目次 • 社内資料を作ることになった経緯 • 資料作成で一番重要視したこと • Sphinxを使おうと思った理由 • Sphinxを使ってよかったこと • 上手くいかなかったこと • まとめ
  9. 9. 資料作成で一番重要視したこと 「何を書くか?」ではなく 「何を書かないか?」を考えて資料を作成。
  10. 10. 理由 題材がGitだから • 書こうと思えば書けることが多すぎる題材。
  11. 11. 資料を作る目的をはっきりさせる • 資料を作ることで「何を達成したいか?」に注目。 • 「業務で何とかついていける下地を作る」ことを目指す。 => 前提知識の記述に集中 (=運用に関することは省く) • 振り返って見通せる量に抑えた説明 • CUIの基礎知識 • 必要最低限のコマンドの使い方 • (Gitの基本構造)
  12. 12. 実際の資料
  13. 13. 説明が足りないところについて • 世にあるGit関連の分かりやすい資料を活用
 • 勉強会中の実演・実際の業務・口頭などで補足
  14. 14. 目次 • 社内資料を作ることになった経緯 • 資料作成で一番重要視したこと • Sphinxを使おうと思った理由 • Sphinxを使ってよかったこと • 上手くいかなかったこと • まとめ
  15. 15. Sphinxを使おうと思った理由 使い慣れていたことが最大の理由 以下の機能が有効活用できそうだと
 アタリがついていた • コマンドラインの記述が割と得意 • 見たままの感じ + コピペのしやすさ • (メンテしやすい)コミットログの図を描く • blockdiagを使用することを想定 • 完全に成功したとは言い難い
  16. 16. 目次 • 社内資料を作ることになった経緯 • 資料作成で一番重要視したこと • Sphinxを使おうと思った理由 • Sphinxを使ってよかったこと • 上手くいかなかったこと • まとめ
  17. 17. Sphinxを使ってよかったこと 目次の自動生成 • 資料の提示順を変更しやすい • 構造が固まりきっていない時は非常に有用 • 資料の入り口を示せば関連資料が全て見える • (関連する資料に限り)散逸しづらい • 章ごとにファイル分割して後でまとめても
 自動で追従してくれる嬉しさ
  18. 18. 目次 • 社内資料を作ることになった経緯 • 資料作成で一番重要視したこと • Sphinxを使おうと思った理由 • Sphinxを使ってよかったこと • 上手くいかなかったこと • まとめ
  19. 19. 上手くいかなかったこと コミットログをblockdiagで無理矢理描いたこと • 複雑でなければ描くのは可能 • しかし、メンテナンス性は悪い(と思う)
  20. 20. 生成した図
  21. 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. 22. 生成した図
  23. 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. 24. 上手くいかなかったこと メンテする機会を
 無くしたつもりではあるけど
 必要な時のメンテがつらい…
  25. 25. 上手くいかなかったこと 予想より各人のサポートする必要があったこと • 資料+αの練習だけでは畳の上の水練でしかない
  26. 26. 目次 • 社内資料を作ることになった経緯 • 資料作成で一番重要視したこと • Sphinxを使おうと思った理由 • Sphinxを使ってよかったこと • 上手くいかなかったこと • まとめ
  27. 27. まとめ 目的に合ったツール選択が重要 • Sphinxに拘らない • メンテナンス性も考慮に入れる
 資料は「書いたら終わり」ではない • 書いた後のことも視野に入れた資料作りが大切
  28. 28. 質問

×