GitHubでポータルサイトドキュメントを運営して幸せになる話 / Operating Portal Site with GitHub Pages

GitHub Satellite Tokyo 2018 の LT にて、登壇したときの資料です。

Transcript

1. Copyright © NTT Communications Corporation. All rights reserved. GitHubでポータルサイト ドキュメントを運営して幸せになる話 GitHub Satellite Tokyo 2018 NTTコミュニケーションズ 岩瀬 義昌 / @iwashi86 2018.6.12
2. GitHub Pages※ 使ってますか？ ※ 詳細は後述するが、簡単に言うとGitHubが提供する静的Webサイトのホスティング機能
3. GitHub Pages と CI/CD ※ を組み合わせてますか？ ※ CI: Continuous Integration、継続的インテグレーションのこと CD: Continuous Delivery・Deployment、継続的デリバリ・デプロイのこと
4. GitHub(Pages)をフル活用して 幸せになる方法を知ること 本LTのゴール
5. ・岩瀬 義昌 / @iwashi86 ・WebRTC※ のPaaSである 　SkyWayのTech Lead ・Fukabori.fm(Podcast)主催 ※ 音声・映像・データをリアルタイムに 　 通信するための技術のこと
6. SkyWayはGitHubと同じく開発者向けのサービス https://webrtc.ecl.ntt.com/
7. GitHub ・gitのホスティング(マネージ)、 　　Pull Request含む開発フロー、SNS など ・OSSや個人Publicリポジトリは無償
8. GitHub ・gitのホスティング(マネージ)、 　　Pull Request含む開発フロー、SNS など ・OSSや個人Publicリポジトリは無償 SkyWay ・WebRTCの面倒なところを 　　マネージドとして提供 ・個人で作るサービスレベル※ ならまず無償 ※ 10万回の接続、500GB/月 のトラフィックは無償
9. 本題
10. GitHub Pagesとは
11. GitHub Pagesとは ・静的Webサイトのホスティング機能
12. GitHub Pagesとは ・静的Webサイトのホスティング機能 ・GitHubがマネージしてくれるため運用レス
13. GitHub Pagesとは ・静的Webサイトのホスティング機能 ・GitHubがマネージしてくれるため運用レス ・開発者の個人ブログだけでなく 　企業のウェブサイトに利用可能
14. gh-pagesの例: MicrosoftのWebサイト https://opensource.microsoft.com/
15. GitHub Pages を使う モチベーションとは？
16. 1. GitHub を使うこと自体のメッセージ 2. CI/CD との組み合わせによる品質向上 補足：そもそも、マネージドによるWebホスティングなどもありますが 　　　SkyWayで活用するにあたり、特に価値があったと考える点に絞ります
17. 1. GitHub を使うこと自体のメッセージ 2. CI/CD との組み合わせによる品質向上
18. 1. GitHub を使うこと自体がメッセージ
19. 1. GitHub を使うこと自体がメッセージ ・SkyWayは2013年12月にリリース 　GitHubのアカウントも公開
20. 1. GitHub を使うこと自体がメッセージ ・SkyWayは2013年12月にリリース 　GitHubのアカウントも公開 ・このときの外部からの声
21. https://twitter.com/laiso/status/410226600362266624
22. 1. GitHub を使うこと自体のメッセージ 2. CI/CD との組み合わせによる品質向上
23. そもそもエンジニア的にはドキュメントを…
24. ・Markdown / reStructuredText で書きたい そもそもエンジニア的にはドキュメントを…
25. ・Markdown / reStructuredText で書きたい ・git で管理して、Pull Request Drivenで 　書きたい＆レビューしたい 　(Wordは現時点でgitに向いていない) そもそもエンジニア的にはドキュメントを…
26. ・Markdown / reStructuredText で書きたい ・git で管理して、Pull Request Drivenで 　書きたい＆レビューしたい ・表記揺れなどのレビューは、 　人間がやるものじゃない そもそもエンジニア的にはドキュメントを…
27. 思いを反映した結果…
28. ドキュメント開発/運用の全体像(SkyWayでの例) 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに 　masterをデプロイ
29. 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加 (MkDocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに 　masterをデプロイ ドキュメント開発/運用の全体像(SkyWayでの例)
30. https://www.mkdocs.org/
31. MkDocs とは ・Markdownで書けるPythonベースの 　静的Webサイトジェネレータ 　 (類似のツールは Sphinx など)
32. MkDocs とは ・Markdownで書けるPythonベースの 　静的Webサイトジェネレータ 　 (類似のツールは Sphinx など) ・ビルドすると、HTML/JS/CSS を吐き出すので、 　それを任意の方法でデプロイする 　 e.g. GitHub Pages、S3へ置く
33. 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに 　masterをデプロイ ドキュメント開発/運用の全体像(SkyWayでの例)
34. textlint とは ・lintは元々、C言語用の構文・文法チェッカだったが 　今では複数言語(e.g. html や golang )に対応
35. textlint とは ・lintは元々、C言語用の構文・文法チェッカだったが 　今では複数言語(e.g. html や golang )に対応 ・textlintは、lintの適用範囲を拡張して、 　文章に適用して、文章品質をテスト可能にしたツール 　(類似のツールは、 RedPen など)
36. textlint とは ・lintは元々、C言語用の構文・文法チェッカだったが 　今では複数言語(e.g. html や golang )に対応 ・textlintは、lintの適用範囲を拡張して、 　文章に適用して、文章品質をテスト可能にしたツール 　(類似のツールは、 RedPen など) ・NGを指摘するだけでなく、自動修正も可能
37. 引用: https://qiita.com/azu/items/e36501d25593d008f6ac textlint の例 人間ではなくプログラムに指摘 -> 修正してもらう
38. 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに 　masterをデプロイ ドキュメント開発/運用の全体像(SkyWayでの例)
39. Circle CIとは ・定番の CI as a Service の1つ
40. Circle CIとは ・定番の CI as a Service の1つ ・リポジトリに書込権限の 　ある鍵を追加することで 　デプロイまで実現可能
41. ドキュメント開発/運用の全体像(SkyWayでの例) 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに 　masterをデプロイ
42. まとめ
43. まとめ - 本日お話したこと
44. まとめ - 本日お話したこと ・GitHubの利用自体がメッセージの1つ
45. まとめ - 本日お話したこと ・GitHubの利用自体がメッセージの1つ ・GitHub Pages を CI/CD と組み合わせる方法
46. まとめ - 本日お話したこと ・GitHubの利用自体がメッセージの1つ ・GitHub Pages を CI/CD と組み合わせる方法 自サイト/ドキュメントの管理に GitHubを活用してはいかがでしょうか？ おしまい