[レポート] GitHub でポータルサイトドキュメントを運用して幸せになる話 #GitHubSatelliteTokyo

こんにちは黒澤です。
GitHub Satellite の Day 1 で開催されたセッション 『GitHub LT大会 ~ 事件は現場で起きている!?』 内で行われた LT
『GitHub でポータルサイトドキュメントを運用して幸せになる話』
についてレポートします。

セッション動画

GitHub SATELLITE TOKYO 2018 Day 1 Community

GitHub でポータルサイトドキュメントを運用して幸せになる話

• スピーカー
  • NTTコミュニケーションズ 岩瀬 義昌様

GitHub Pages とは

• 静的 Web サイトのホスティング機能
• GitHub がマネージしてくれるため運用レス
• 開発者の個人ブログだけでなく企業の Web サイトに利用可能
• GitHub Pages の例 :
  • Open Source - Microsoft

GitHub Pages を使うモチベーションとは

1. GitHub を使うこと自体のメッセージ
2. CI/CD との組み合わせによる品質向上

GitHub を使うこと自体のメッセージ

• 会社として GitHub のアカウントを出すと外部へのアピールに繋がる

CI/CD との組み合わせによる品質向上

そもそもエンジニア的にはドキュメントを

• Markdown/reStructuredText で書きたい
• Git で管理して Pull Request Driven で書きたい & レビューしたい
  • Word は現時点では Git 管理に向いていない
• 表記揺れなどのレビューは人間がやるものじゃない

ドキュメント開発/運用の全体像

MkDocs とは

MkDocs

• Markdown で書くことができる Python ベースの静的 Web サイトジェネレータ
  • 類似のツール : Sphinx など
• ビルドすると HTML/JS/CSS を吐き出すのでそれを任意の方法でデプロイする
  • GitHub Pages、S3 へ置く

textlint とは

textlint

• lint は元々C言語の構文/文法チェッカだったが、今では複数言語に対応
• textlint は lint の適用範囲を拡張して、文章に適用することで文章品質をテスト可能にしたツール
  • 類似のツール : RedPen など
• NG を指摘するだけでなく自動修正も可能

Circle CI とは

CircleCI

• 定番の CI as a Service の一つ
• リポジトリに書込権限のある鍵を追加することでデプロイまで実現可能

まとめ

• GitHub の利用自体がメッセージの一つ
• GitHub Pages を CI/CD と組み合わせる方法
• 自サイト/ドキュメントの管理に GitHub を活用しよう

さいごに

みなさんいかがでしたでしょうか。10分という短い時間の中での LT でしたが内容の濃いお話を聞くことができました。エンジニアとしてドキュメント管理をこうしたいって話はすごくあるあるな話だと思います。実際の構成やフローについても解説いただきとてもためになるお話でした。