システム開発におけるドキュメントをできるだけGithub Pagesに集約してみた話

by caad TakaraShinya

Slide 1

Slide 1 text

システム開発におけるドキュメントをできるだけGithub Pages に集約してみた話 @takarake Hackers Champloo 2023 #hcmpl

Slide 2

Slide 2 text

アジェンダ 1️⃣ 自己紹介 2️⃣ 今回話すこと 3️⃣ Github Pages 、Wiki とは何か 4️⃣ 結果 5️⃣ Github Pages へのドキュメントの集約方法 6️⃣ まとめ

Slide 3

Slide 3 text

1️⃣ 自己紹介

Slide 4

Slide 4 text

自己紹介( 真面目用)

Slide 5

Slide 5 text

自己紹介(X @takarake)

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

自己紹介❓ではないですが、、、、

Slide 8

Slide 8 text

2️⃣ 今回話すこと

Slide 9

Slide 9 text

皆さん、業務中ドキュメントが散らかってて困ったこと、ありませんか❓

Slide 10

Slide 10 text

よし、ブラウザで別タブ開いて探そう❗

Slide 11

Slide 11 text

あーログインね、スマホで２段階認証して📱

Slide 12

Slide 12 text

あれ、何するんだっけ？ってことありません❓挙手🙋‍♂

Slide 13

Slide 13 text

お恥ずかしい話ですが、私はよくあります😭

Slide 14

Slide 14 text

原因はまあ皆さんご存知の２段階認証やその他もろもろですよね・・・・💦

Slide 15

Slide 15 text

よし、ブラウザで別タブ開いて探そう❗ 👇 新しいタブ開いて検索する🔍 👇 画面開くけど、ログイン求められる😭 👇 1password 等から情報拾ってログイン🔑 👇つづく

Slide 16

Slide 16 text

👇 ２段階認証の通知がスマホに届く📱 👇 なんか見慣れない通知きてる❗認証だけ対応して見よ👀 👇 その結果、スマホとお友達になる🤝(youtube とか見ちゃうｗ) 👇 ついでにLINE も見ちゃう📱

Slide 17

Slide 17 text

👇 仕事に戻る💻 👇 あれ、何するんだっけ❓

Slide 18

Slide 18 text

チーン💦

Slide 19

Slide 19 text

今日の話はこのような事象を解決するために、私がこうやってみたという一つのチャレンジ例です👍

Slide 20

Slide 20 text

この事象はドキュメントだけに限らず起きていますが、エンジニアの皆さんはGithub は開いてますよね❓

Slide 21

Slide 21 text

他によく使われるドキュメントって何があるか❓🤔

Slide 22

Slide 22 text

Google スライド Google スプレッドシート Google ドキュメント Notion Qiita Team Confluence

Slide 23

Slide 23 text

自分たちは他の使ってるって方いますか❓🤔挙手🙋‍♂ Google スライド Google スプレッドシート Google ドキュメント Notion Qiita Team Confluence

Slide 24

Slide 24 text

ほぼ全部Github と別でログインするやつじゃん❓🤔 Google スライド Google スプレッドシート Google ドキュメント Notion Qiita Team Confluence

Slide 25

Slide 25 text

けど、Github にWiki とかPages ってあったよね❓🤔

Slide 26

Slide 26 text

3️⃣ Github Pages 、Wiki とは何か

Slide 27

Slide 27 text

3️⃣ Github Pages 、Wiki とは何か GitHub Pages とは GitHub のリポジトリから HTML 、CSS 、および JavaScript ファイルを直接取得し、任意でビルドプロセスを通じてファイルを実行し、ウェブサイトを公開できる静的なサイトホスティングサービスです。 GitHub の github.io ドメインまたは独自のカスタムドメインでサイトをホストできます。 ※docs.github.com より引用テキストで説明されても・・・・・ってなりますよね💦

Slide 28

Slide 28 text

3️⃣ Github Pages 、Wiki とは何か GitHub Pages とは

Slide 29

Slide 29 text

3️⃣ Github Pages 、Wiki とは何か先程のリポジトリでデプロイしたGithub Pages のサイトです

Slide 30

Slide 30 text

3️⃣ Github Pages 、Wiki とは何か Github のWiki とは GitHub.com のすべてのリポジトリには、Wiki と呼ばれるドキュメントをホストするためのセクションが用意されています。リポジトリのウィキは、プロジェクトの利用方法、設計方法、中核的な原理など、プロジェクトに関する長いコンテンツを共有するために利用できます。 ※docs.github.com より引用同じくテキストで説明されても💦

Slide 31

Slide 31 text

3️⃣ Github Pages 、Wiki とは何か Github のWiki とは

Slide 32

Slide 32 text

しかし、Pages とWiki には長年利用されにくい問題があった💦

Slide 33

Slide 33 text

Wiki やPages 利用時にあった問題👀 Github Pages がPublic でしか使えない💦 画像貼ったりするとURL がパブリックなURL になって危険⚡ ER 図とかなにか図形を書いて表現したいとき表現力不足💦 Markdown で書かないといけない💦 たくさん記事書くと次は検索し辛い💦

Slide 34

Slide 34 text

しかし、ついにGithub さんやその他OSS が解決してくれました👍

Slide 35

Slide 35 text

個人的に一番助かると思ったのが、これ👇 🙌 プライベートでPages 作れる❗ 🙌

Slide 36

Slide 36 text

さらに私を助けたのがこれ👇 🙌 添付ファイルもプライベートにできる❗ 🙌

Slide 37

Slide 37 text

次点がこれ👇 🙌 mermaid で各種の図が書ける❗ 🙌

Slide 38

Slide 38 text

そしてMarkdown で書いた文書を静的サイト化できるツールがこれ👇 🙌 docs サイト作ればドキュメント更新もGithub 管理できる❗ 🙌

Slide 39

Slide 39 text

この４つがあればPages でドキュメントサイト構築できそう🤔

Slide 40

Slide 40 text

ここから私はGithub Pages を使ってドキュメントを集約してみようと思いました👍

Slide 41

Slide 41 text

4️⃣ 結果

Slide 42

Slide 42 text

もうめんどくさいので、結果から見せてしまいます❗

Slide 43

Slide 43 text

できあがったサイトがこちら👇 https://takarashinya.github.io/docs-to-githubpages/

Slide 44

Slide 44 text

5️⃣ Github Pages へのドキュメントの集約方法

Slide 45

Slide 45 text

利用したツールや記法たち Markdown( 当然) 皆さんご存知の文書を記述するための軽量マークアップ言語 mdbook Markdown を用いて文書を作成できるRust 製のツール tbls CI フレンドリーなGo で書かれたデータベースドキュメントツール mermaid ダイアグラム作成およびチャート作図用のJavaScript ライブラリ plantuml UML （Unified Modeling Language ：統一モデリング言語）のダイアグラムを作成するためのオープンソースのツール SSGform( 問合せフォームに利用) SSGform （エスエスジーフォーム）はフォームを簡単に設置できるサービス ChatGPT(Azure OpenAI Service GPT-4 の方)

Slide 46

Slide 46 text

6️⃣ まとめ

Slide 47

Slide 47 text

6️⃣ まとめ Github の進化でdocs 作成と提供がしやすくなって嬉しい🙌 CI フレンドリーにER 図、テーブル定義書、システム構成図も作れて便利👍 Markdown や plantuml 、mermaid 記法は覚えないといけない💦 plantuml と mermaid はもうmermaid の勝ち❓🤔 次はコードが吐き出されるともっと良くなる(ChatGPT ではもうできる😲)

Slide 48

Slide 48 text

👂ご静聴ありがとうございました👂