Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

社内のマニュアルをSphinxで作ってみた

1,433 views

Published on

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

Published in: Technology
  • Be the first to comment

社内のマニュアルをSphinxで作ってみた

  1. 1. 1 社内の マニュアルを Sphinxで 作ってみたIosif Takakura (@huideyeren) 1
  2. 2. 2 はじめに
  3. 3. 3 自己紹介 名前:Iosif Takakura 所属:とあるアパレル系の特例子会社 職種:一応エンジニアになりました レガシーシステムとExcel方眼紙のお守りをしてます 主な技術:C#、JS、Ruby Pythonは学習中 興味のあること 機械学習 モバイルプログラミング ソーシャルネットワーク 発達障がい当事者
  4. 4. 4 Sphinxとのかかわり 1. すでに退社した某氏による紹介 2. 同人誌を書くのに使ってみた ただし新刊はRe:VIEWに移行 3. 社内ドキュメントをSphinxで作ってみた 今日はこの話を予定 どう書くか、といった話は少なめ むしろ技術的負債メインだよ
  5. 5. 5 導入編
  6. 6. 6 Sphinxで書いたマニュアル 業務マニュアル 技術解説文書
  7. 7. 7 業務マニュアルが必要になる背景 HP作成業務でドキュメントが必要だった 1. HP作成にMiddlemanを使った 2. Middleman扱える人の退社が相次ぐ 3. 最低限更新ができるレベルのマニュアルがほしい 4. Sphinxで書いた Excel方眼紙大嫌い 2次元的な表現(図表・グラフなど)が苦手 レイアウトを決めながら文書を書けないタイプ 文章はそこまで苦手じゃない ただし長くなる傾向あり Excelは単一ファイルなので同時編集できない Sphinxなら分担して書きやすい
  8. 8. 8 技術解説文書を残した理由 中身を理解していじれる人が1人になってしまった 想定読者が「この通りに操作すれば更新できる」レベル だけどこんなんじゃぜんぜんたりない 技術とともにエンジニアとしての心構えを伝えたかった
  9. 9. 9 社内環境 勝手にソフトウェアを入れられる環境にない ただし、社内ネットワークの管理外ならOK Macは社内ネットワーク管理外 親会社IT部門の管轄下 技術的にはWindowsメイン 結局、独断で導入した 様々な技術レベルの人が混在 社内にはWordやExcelしかできない人も コマンドライン使えるのはごく少数 Excel方眼紙が跳梁跋扈 勘弁してください コスト管理はしっかりしている ただし、余計な工数は割きづらい
  10. 10. 10 なぜ業務マニュアルにSphinxを使ったか HTMLで見やすいドキュメントができる 図表が苦手な私にとって助かる でもスクリーンショットは必要 レイアウトとコンテンツを分離できるため MacはIT部門の管轄外 独断で環境を整える場合Macしか選択肢がない
  11. 11. 11 文書の作成 内部の構成は分けられるように includeを多用 toctreeで項目ごとに書いていく apidoc的なものは一切使ってない まあRubyだし…… 連携できる何かはあるのだろうけど知らなかった Pandocを使ってMarkdownから変換 素のreST教えるよりよいかな、と これからのスキルにMarkdownは必須、ということで 余計に書きすぎる癖が炸裂 内容の校正に時間がかかってしまった
  12. 12. 12 開発環境 macOS Python3 Atom Pandoc MacTeX CIとかは使わない
  13. 13. 13 執筆者 私 Aさん 2016年度の新人 ITスキルはある方 Java経験あり ただしSphinxは初めて UNIX系経験も多いとは言えない CUIに慣れていない
  14. 14. 14 完成後の運用編
  15. 15. 15 チームメンバーの変遷 1. 社内でソフトウェア開発に取り組むため私がチームを抜ける このときAさんに内部の詳細まで教えきれなかった 2. Aさんがさらに新人Bさんに教える 3. そのAさんも開発案件に専従になる 4. Bさんが中心となってプロジェクトの保守を行っている 5. 現在、Bさんは新人Cさんにプロジェクトのことを教えている ドキュメントの不備が山のように見つかる 6. 別案件に忙殺されて私はドキュメントをメンテナンスできない
  16. 16. 16 ドキュメントのメンテナンス メンテナンスには手間がかかっていた わざわざMacに行くのが大変 reSTやMarkdownは学習コストがかかる Sphinx本なんてあるわけない 上司「なぜExcelやパワポで作らないの?」 Excelやパワポなら一応誰でも使える うまく反論できなかった 余計に書く癖がどんどん文書量を増やしてしまう ドキュメントのダイエットが必要 結果的にメンテナンスコストが増大 学習コストに割ける工数がなくなってしまった
  17. 17. 17 メンテナンスコストがかかると 1. メンテナンスされなくなる 2. 現実と内容の乖離 3. 修正の仕方がわからない 4. 放置されて技術的負債に…… 5. 枯れた技術でリプレース! 実際、ドキュメントは素のHTML で書き直されつつあります……
  18. 18. 18 ふりかえり
  19. 19. 19 教訓 独断での技術の導入はうまくいかない事が多い 組織がボトムアップ的改善を受け入れる余地がないと厳しい コストや周りの人の技術レベルなども考える必要がある 理解の難しい技術はオーパーツ化し、技術的負債になりやすい 最悪、ドキュメント自体が技術的負債になる 中心メンバーが抜けた後の運用も考える必要がある 特に、知識や技術の伝授をしっかりと コストについて考えることも忘れずに 楽に書けても学習コストが高いと釣り合わない それ故に誰でも使えるExcelなどが選択されやすい
  20. 20. 20 技術的負債とどう向き合うか 1. わかりやすい技術・構造を選択する 技術レベルに合わない技術は爆死しやすい かといって枯れすぎた技術を選んでも爆死する 2. 周りの人やマネージャー、経営層に説明できるようにする ここをうまくやらないと導入はうまくいかない マネージャーや経営層には数字で説得できる必要がある 特に、工数やコストは非常に重要 さらに、顧客にも説明できるとなおよい 3. 共通の認識を持てるように技術・知識を社内で広める 教え方を常に磨く必要がある 4. 共通認識ができたら技術的負債の解消に向けて動く 個人的には技術的負債と向き合う時期を作りたい そのためには常にコミュニケーションする事を忘れずに。
  21. 21. 21 メンテされやすいドキュメントの作り方 1. 「何で作るか」にこだわってはいけない ただし、誰でも編集できることは大事 ドキュメント作成者のスキルセットを考えよう 2. 必要最低限のドキュメントだけ作る 3. 定期的にメンテナンスする機会を設ける 4. コミュニケーション、大事! 積極的にコミュニケーションしよう 5. コスト意識を忘れずに その中には学習コストも含まれる
  22. 22. 22 おしまい ご清聴ありがとうございました

×