自動化大好きエンジニアLT会 - vol.9で発表したスライドとなります

1. エンジニアライクに
ドキュメントをつくって
みた件
MIHOSHIMA(MIHO MATSUSHIMA)
@自動化大好きエンジニアLT会 - VOL.9

2. 自己紹介
Miho Matsushima/@enenae0927
• 某SIerのインフラ事業部門所属
• 好きな技術
• コンテナ(Amazon ECS/K8s)
• CI/CD（Code3兄弟)…etc
単調な作業が苦手なので、できれば自動化して楽し
たい派

3. 今回登壇に至った経緯
• 弊社にも自動化に関する社内コミュニティが存在
• ラクスさん同様、LTで自動化の知見を共有
• 他社さんがどんなことされているのか興味津々
• 社外で登壇してみたかったし参加しよ（→いまここ）

4. 本LTで目指したいゴール
• ドキュメント作成をCI/CDでやるための方法がわかる
• ドキュメント作成をCI/CDでやってよかったことがお伝えできている

5. ドキュメントCI/CDってなんだ？
• CI/CDとはビルド、テスト、デプロイを自動化する開発の手法
• 一般的にはソフトウェア(プログラム)開発で使われる
• 今回のLTでは、それを“ドキュメント“に適用したお話となります
CIツール
デプロイ
環境
Aブランチで
コードを変更
GitHub/GitLab/
CodeCommit
コード
リポジトリ
開発者
Jenkins/CodeBuild
マスターマージを
検知
ビルド/自動テス
ト 異常がなければ
自動リリース
Aブランチを確認
問題がなければ
マスターマージ
レビュー
アー

6. ドキュメントにCI/CDを
適用しようと思ったきっかけ

7. ある日仕事の中でこんな活動が爆誕
良いですね、、、ただ、
ドキュメントの作成手順は
こちらで考えさせてください
技術検証の結果や
クラウドサービスでの設計ポイントを
有識者達がまとめて
知見共有できないかな？

8. WordやPowerPointを
共有ドライブに置くのじゃダ
メ？

9. 過去の悲劇を繰り返したくない
共同編集による
バージョン管理地
獄
置き場がわからず、
作ったのに読まれな
い
レビューになんだか
んだ
時間がかかる
クラウド設計ガイド.pptx
クラウド設計ガイド_v1.pptx
クラウド設計ガイド_v1_最新.pptx
クラウド設計ガイド_v1_田中編集.pptx
…
何が
変更された
…?
せっかく
作ったのに

10. 当初の私の気持ち
• 複数の編集者が都度更新をかけるなら、Gitでバージョン管理したい
• さらにいうと、Pull & Requestでレビューしたい
• Webで限定公開し、ここにいけば良いという場所を作りたい
• 最新のファイル、誰かおいてくれました？みたいな状況も防ぎたい＝リリースを自動化したい
• HTMLやCSSで見栄えが良いほうが読み手のモチベーションも上がりそう
• さらにいうと、ビルドすれば手軽にHTMLに変換できるし、書き慣れたMarkdown使いたい
• 表記ゆれや単語の言い間違いは機械的にチェックしたい
• ただでさえ、業務の合間にする活動なので無駄な労力はかけたくない

11. Markdownで書いて、
CI/CDで良い感じに公開しよ
う

12. 結果こうなった
Aブランチで
ドキュメントを
変更
開発者
Aブランチを確認
問題がなければ
マスターマージ
レビュー
アー
マスターマージを
検知
Markdown→HTMLにビルド
S3に自動
デプロイ
ブラウザから
良い感じに見れる
textlintで
表記ゆれを自動修正

13. 大事な技術要素(MkDocs)
• Markdown形式でウェブサイトが作成できる静的サイトジェネレータ
• ビルドするとHTML/CSS/JSが生成されるので、任意のWebサーバにデプロイす
即座に公開が可能
• 様々なテーマや拡張機能でデザインをカスタマイズ可能
• テーマを選ぶことができ、好みに合わせてWeb全体のデザインを変えらえれる
• テーマを自分で作成することも可能
• メモ、ヒント、警告などが目立つようなスタイルを適用可
• Font Awesomeによる装飾が可能

14. Mkdocsのイメージ
引用元：https://fereria.github.io/reincarnation_tech/

15. 大事な技術要素(textlint)
• textlintはMarkdownなどテキスト向けのLint(校正)ツール
• lintはコードの内容を自動的に検査し、悪い書き方を指摘して、修正を促すツール
• textlintはプログラミング言語ではなく自然言語に対応している
• テストするルールはカスタマイズ（npmで適宜インストール)可能
• 技術文書を対象としたプリセット(おすすめ)：
『textlint-rule-preset-ja-technical-writing』
• VSCodeの拡張機能にも対応しているので、エディタ上でも校正可能

16. 導入してよかったこと
リリースや誤字脱字確認を
機械的にできるので
作業が楽になった
Webで公開したことで、
見栄えよし
すぐ“ここにあるよ”
といえる
普段コードを
書かないメンバの
Git力向上につながった

17. まとめ
• ドキュメント作成はMarkdown、CI/CDや各種ツールを使うと
効率的になる
• 各種ツールとは
• Mkdocs： Markdownに対応した静的サイトジェネレータ
• textlint：Markdown等のテキスト校正ツール
• MarkdownをHTMLで公開すると、見栄え/アクセシビリティが向上

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