社内のマニュアルをSphinxで作ってみたら見事に技術的負債になった話。

1. 1
社内の
マニュアルを
Sphinxで
作ってみたIosif Takakura
(@huideyeren)
1

2. 2
はじめに

3. 3
自己紹介
名前：Iosif Takakura
所属：とあるアパレル系の特例子会社
職種：一応エンジニアになりました
レガシーシステムとExcel方眼紙のお守りをしてます
主な技術：C#、JS、Ruby
Pythonは学習中
興味のあること
機械学習
モバイルプログラミング
ソーシャルネットワーク
発達障がい当事者

4. 4
Sphinxとのかかわり
1. すでに退社した某氏による紹介
2. 同人誌を書くのに使ってみた
ただし新刊はRe:VIEWに移行
3. 社内ドキュメントをSphinxで作ってみた
今日はこの話を予定
どう書くか、といった話は少なめ
むしろ技術的負債メインだよ

5. 5
導入編

6. 6
Sphinxで書いたマニュアル
業務マニュアル
技術解説文書

7. 7
業務マニュアルが必要になる背景
HP作成業務でドキュメントが必要だった
1. HP作成にMiddlemanを使った
2. Middleman扱える人の退社が相次ぐ
3. 最低限更新ができるレベルのマニュアルがほしい
4. Sphinxで書いた
Excel方眼紙大嫌い
2次元的な表現（図表・グラフなど）が苦手
レイアウトを決めながら文書を書けないタイプ
文章はそこまで苦手じゃない
ただし長くなる傾向あり
Excelは単一ファイルなので同時編集できない
Sphinxなら分担して書きやすい

8. 8
技術解説文書を残した理由
中身を理解していじれる人が1人になってしまった
想定読者が「この通りに操作すれば更新できる」レベル
だけどこんなんじゃぜんぜんたりない
技術とともにエンジニアとしての心構えを伝えたかった

9. 9
社内環境
勝手にソフトウェアを入れられる環境にない
ただし、社内ネットワークの管理外ならOK
Macは社内ネットワーク管理外
親会社IT部門の管轄下
技術的にはWindowsメイン
結局、独断で導入した
様々な技術レベルの人が混在
社内にはWordやExcelしかできない人も
コマンドライン使えるのはごく少数
Excel方眼紙が跳梁跋扈
勘弁してください
コスト管理はしっかりしている
ただし、余計な工数は割きづらい

10. 10
なぜ業務マニュアルにSphinxを使ったか
HTMLで見やすいドキュメントができる
図表が苦手な私にとって助かる
でもスクリーンショットは必要
レイアウトとコンテンツを分離できるため
MacはIT部門の管轄外
独断で環境を整える場合Macしか選択肢がない

11. 11
文書の作成
内部の構成は分けられるように
includeを多用
toctreeで項目ごとに書いていく
apidoc的なものは一切使ってない
まあRubyだし……
連携できる何かはあるのだろうけど知らなかった
Pandocを使ってMarkdownから変換
素のreST教えるよりよいかな、と
これからのスキルにMarkdownは必須、ということで
余計に書きすぎる癖が炸裂
内容の校正に時間がかかってしまった

12. 12
開発環境
macOS
Python3
Atom
Pandoc
MacTeX
CIとかは使わない

13. 13
執筆者
私
Aさん
2016年度の新人
ITスキルはある方
Java経験あり
ただしSphinxは初めて
UNIX系経験も多いとは言えない
CUIに慣れていない

14. 14
完成後の運用編

15. 15
チームメンバーの変遷
1. 社内でソフトウェア開発に取り組むため私がチームを抜ける
このときAさんに内部の詳細まで教えきれなかった
2. Aさんがさらに新人Bさんに教える
3. そのAさんも開発案件に専従になる
4. Bさんが中心となってプロジェクトの保守を行っている
5. 現在、Bさんは新人Cさんにプロジェクトのことを教えている
ドキュメントの不備が山のように見つかる
6. 別案件に忙殺されて私はドキュメントをメンテナンスできない

16. 16
ドキュメントのメンテナンス
メンテナンスには手間がかかっていた
わざわざMacに行くのが大変
reSTやMarkdownは学習コストがかかる
Sphinx本なんてあるわけない
上司「なぜExcelやパワポで作らないの？」
Excelやパワポなら一応誰でも使える
うまく反論できなかった
余計に書く癖がどんどん文書量を増やしてしまう
ドキュメントのダイエットが必要
結果的にメンテナンスコストが増大
学習コストに割ける工数がなくなってしまった

17. 17
メンテナンスコストがかかると
1. メンテナンスされなくなる
2. 現実と内容の乖離
3. 修正の仕方がわからない
4. 放置されて技術的負債に……
5. 枯れた技術でリプレース！
実際、ドキュメントは素のHTML で書き直されつつあります……

18. 18
ふりかえり

19. 19
教訓
独断での技術の導入はうまくいかない事が多い
組織がボトムアップ的改善を受け入れる余地がないと厳しい
コストや周りの人の技術レベルなども考える必要がある
理解の難しい技術はオーパーツ化し、技術的負債になりやすい
最悪、ドキュメント自体が技術的負債になる
中心メンバーが抜けた後の運用も考える必要がある
特に、知識や技術の伝授をしっかりと
コストについて考えることも忘れずに
楽に書けても学習コストが高いと釣り合わない
それ故に誰でも使えるExcelなどが選択されやすい

20. 20
技術的負債とどう向き合うか
1. わかりやすい技術・構造を選択する
技術レベルに合わない技術は爆死しやすい
かといって枯れすぎた技術を選んでも爆死する
2. 周りの人やマネージャー、経営層に説明できるようにする
ここをうまくやらないと導入はうまくいかない
マネージャーや経営層には数字で説得できる必要がある
特に、工数やコストは非常に重要
さらに、顧客にも説明できるとなおよい
3. 共通の認識を持てるように技術・知識を社内で広める
教え方を常に磨く必要がある
4. 共通認識ができたら技術的負債の解消に向けて動く
個人的には技術的負債と向き合う時期を作りたい
そのためには常にコミュニケーションする事を忘れずに。

21. 21
メンテされやすいドキュメントの作り方
1. 「何で作るか」にこだわってはいけない
ただし、誰でも編集できることは大事
ドキュメント作成者のスキルセットを考えよう
2. 必要最低限のドキュメントだけ作る
3. 定期的にメンテナンスする機会を設ける
4. コミュニケーション、大事！
積極的にコミュニケーションしよう
5. コスト意識を忘れずに
その中には学習コストも含まれる

22. 22
おしまい
ご清聴ありがとうございました