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

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

清水琢 (@takuan_osho)

SphinxCon JP 2015

自己紹介

清水琢　(@takuan_osho)

• 非IT系企業で社内システムのお守り

• いわゆる社内SE的な仕事をしている

• Sphinxとの関わり

• 初めて触れたのがSphinx翻訳ハッカソン(2011/2/12)

• 「翻訳」の部分に惹かれて初参加

• それから色々なコミュニティに参加するようになる

話すこと

今回話したいことはだいたい以下の通り。

• 事例紹介

• (Sphinxを使った時の)社内勉強会資料作成の考え方

• 「何故この選択をしたか？」ということについて

話さないこと

今回触れないことは以下の通り。

• Sphinxの機能紹介・深い使い方

目次

• 社内資料を作ることになった経緯

• 資料作成で一番重要視したこと

• Sphinxを使おうと思った理由

• Sphinxを使ってよかったこと

• 上手くいかなかったこと

• まとめ

社内資料を作ることになった経緯

Gitが新しく導入される。

• 日付バージョン管理辛いので導入された。 • チームメンバーの大半が

Gitにそれほど精通していない

=> 社内勉強会の必要性

• 上司から勉強会用の資料を

作るように言われる。

目次






• まとめ

資料作成で一番重要視したこと

「何を書くか？」ではなく

「何を書かないか？」を考えて資料を作成。

理由

題材がGitだから

• 書こうと思えば書けることが多すぎる題材。

資料を作る目的をはっきりさせる

• 資料を作ることで「何を達成したいか？」に注目。

• 「業務で何とかついていける下地を作る」ことを目指す。

=> 前提知識の記述に集中 (=運用に関することは省く)

• 振り返って見通せる量に抑えた説明

• CUIの基礎知識

• 必要最低限のコマンドの使い方

• (Gitの基本構造)

実際の資料

説明が足りないところについて

• 世にあるGit関連の分かりやすい資料を活用

• 勉強会中の実演・実際の業務・口頭などで補足

目次






• まとめ

Sphinxを使おうと思った理由

使い慣れていたことが最大の理由以下の機能が有効活用できそうだと

アタリがついていた • コマンドラインの記述が割と得意

• 見たままの感じ + コピペのしやすさ

• (メンテしやすい)コミットログの図を描く

• blockdiagを使用することを想定

• 完全に成功したとは言い難い

目次






• まとめ

Sphinxを使ってよかったこと

目次の自動生成 • 資料の提示順を変更しやすい

• 構造が固まりきっていない時は非常に有用

• 資料の入り口を示せば関連資料が全て見える

• (関連する資料に限り)散逸しづらい

• 章ごとにファイル分割して後でまとめても

自動で追従してくれる嬉しさ

目次






• まとめ

上手くいかなかったこと

コミットログをblockdiagで無理矢理描いたこと

• 複雑でなければ描くのは可能

• しかし、メンテナンス性は悪い(と思う)

生成した図

生成した図のもとのコード 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 } }

生成した図

生成した図のもとのコード 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"] } }


メンテする機会を

無くしたつもりではあるけど

必要な時のメンテがつらい…


予想より各人のサポートする必要があったこと

• 資料+αの練習だけでは畳の上の水練でしかない

目次






• まとめ

まとめ

目的に合ったツール選択が重要

• Sphinxに拘らない

• メンテナンス性も考慮に入れる

資料は「書いたら終わり」ではない • 書いた後のことも視野に入れた資料作りが大切

質問

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

Technology

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