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

Slide 1

Slide 1 text

Slide 2

Slide 2 text

GitHub Pages※ 使ってますか？ ※ 詳細は後述するが、簡単に言うとGitHubが提供する静的Webサイトのホスティング機能

Slide 3

Slide 3 text

GitHub Pages と CI/CD ※ を組み合わせてますか？ ※ CI: Continuous Integration、継続的インテグレーションのこと CD: Continuous Delivery・Deployment、継続的デリバリ・デプロイのこと

Slide 4

Slide 4 text

GitHub(Pages)をフル活用して幸せになる方法を知ること本LTのゴール

Slide 5

Slide 5 text

・岩瀬義昌 / @iwashi86 ・WebRTC※ のPaaSである　SkyWayのTech Lead ・Fukabori.fm(Podcast)主催 ※ 音声・映像・データをリアルタイムに　通信するための技術のこと

Slide 6

Slide 6 text

SkyWayはGitHubと同じく開発者向けのサービス https://webrtc.ecl.ntt.com/

Slide 7

Slide 7 text

GitHub ・gitのホスティング(マネージ)、　　Pull Request含む開発フロー、SNS など・OSSや個人Publicリポジトリは無償

Slide 8

Slide 8 text

GitHub ・gitのホスティング(マネージ)、　　Pull Request含む開発フロー、SNS など・OSSや個人Publicリポジトリは無償 SkyWay ・WebRTCの面倒なところを　　マネージドとして提供・個人で作るサービスレベル※ ならまず無償 ※ 10万回の接続、500GB/月のトラフィックは無償

Slide 9

Slide 9 text

本題

Slide 10

Slide 10 text

GitHub Pagesとは

Slide 11

Slide 11 text

GitHub Pagesとは・静的Webサイトのホスティング機能

Slide 12

Slide 12 text

GitHub Pagesとは・静的Webサイトのホスティング機能・GitHubがマネージしてくれるため運用レス

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

gh-pagesの例: MicrosoftのWebサイト https://opensource.microsoft.com/

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

1. GitHub を使うこと自体のメッセージ 2. CI/CD との組み合わせによる品質向上補足：そもそも、マネージドによるWebホスティングなどもありますが　　　SkyWayで活用するにあたり、特に価値があったと考える点に絞ります

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

1. GitHub を使うこと自体がメッセージ

Slide 19

Slide 19 text

1. GitHub を使うこと自体がメッセージ・SkyWayは2013年12月にリリース　GitHubのアカウントも公開

Slide 20

Slide 20 text

1. GitHub を使うこと自体がメッセージ・SkyWayは2013年12月にリリース　GitHubのアカウントも公開・このときの外部からの声

Slide 21

Slide 21 text

https://twitter.com/laiso/status/410226600362266624

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

・Markdown / reStructuredText で書きたいそもそもエンジニア的にはドキュメントを…

Slide 25

Slide 25 text

・Markdown / reStructuredText で書きたい・git で管理して、Pull Request Drivenで　書きたい＆レビューしたい　(Wordは現時点でgitに向いていない) そもそもエンジニア的にはドキュメントを…

Slide 26

Slide 26 text

・Markdown / reStructuredText で書きたい・git で管理して、Pull Request Drivenで　書きたい＆レビューしたい・表記揺れなどのレビューは、　人間がやるものじゃないそもそもエンジニア的にはドキュメントを…

Slide 27

Slide 27 text

思いを反映した結果…

Slide 28

Slide 28 text

ドキュメント開発/運用の全体像(SkyWayでの例) 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使ったテスト実行 ①ブランチを切って文書を追加(mkdocs) ④レビューReady を通知その他メンバ ⑤文書レビュー ⑥GitHub Pagesに　masterをデプロイ

Slide 29

Slide 29 text

開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使ったテスト実行 ①ブランチを切って文書を追加 (MkDocs) ④レビューReady を通知その他メンバ ⑤文書レビュー ⑥GitHub Pagesに　masterをデプロイドキュメント開発/運用の全体像(SkyWayでの例)

Slide 30

Slide 30 text

https://www.mkdocs.org/

Slide 31

Slide 31 text

MkDocs とは・Markdownで書けるPythonベースの　静的Webサイトジェネレータ　 (類似のツールは Sphinx など)

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使ったテスト実行 ①ブランチを切って文書を追加(mkdocs) ④レビューReady を通知その他メンバ ⑤文書レビュー ⑥GitHub Pagesに　masterをデプロイドキュメント開発/運用の全体像(SkyWayでの例)

Slide 34

Slide 34 text

textlint とは・lintは元々、C言語用の構文・文法チェッカだったが　今では複数言語(e.g. html や golang )に対応

Slide 35

Slide 35 text

textlint とは・lintは元々、C言語用の構文・文法チェッカだったが　今では複数言語(e.g. html や golang )に対応・textlintは、lintの適用範囲を拡張して、　文章に適用して、文章品質をテスト可能にしたツール　(類似のツールは、 RedPen など)

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

引用: https://qiita.com/azu/items/e36501d25593d008f6ac textlint の例人間ではなくプログラムに指摘 -> 修正してもらう

Slide 38

Slide 38 text

Slide 39

Slide 39 text

Circle CIとは・定番の CI as a Service の1つ

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

Slide 42

Slide 42 text

まとめ

Slide 43

Slide 43 text

まとめ - 本日お話したこと

Slide 44

Slide 44 text

まとめ - 本日お話したこと・GitHubの利用自体がメッセージの1つ

Slide 45

Slide 45 text

まとめ - 本日お話したこと・GitHubの利用自体がメッセージの1つ・GitHub Pages を CI/CD と組み合わせる方法

Slide 46

Slide 46 text

まとめ - 本日お話したこと・GitHubの利用自体がメッセージの1つ・GitHub Pages を CI/CD と組み合わせる方法自サイト/ドキュメントの管理に GitHubを活用してはいかがでしょうか？おしまい