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

皆さん、開発してる中でドキュメントが散らかっててストレスになったり、困ったりしたこと、ありませんか❓
このトークではよくあるシステム開発プロジェクトにて発生する各種ドキュメント郡をなるべくGithub Pagesに集めてみた話をします 🦜
これらをどうやったのか、やってみてどうだったのかや面白くなってきて○○まで作ってみた的なお話ができればと思います。
レギュラートークレベルで内容が濃いかは別です^^;

Transcript

1. システム開発におけるドキュメ ントをできるだけGithub Pages に集約してみた話 @takarake Hackers Champloo 2023 #hcmpl
2. アジェンダ 1️⃣ 自己紹介 2️⃣ 今回話すこと 3️⃣ Github Pages 、Wiki とは何か 4️⃣ 結果 5️⃣ Github Pages へのドキュメントの集約方法 6️⃣ まとめ
3. 1️⃣ 自己紹介
4. 自己紹介( 真面目用)
5. 自己紹介(X @takarake)
7. 自己紹介❓ではないですが、、、、
8. 2️⃣ 今回話すこと
9. 皆さん、業務中ドキュメントが散らかってて困ったこ と、ありませんか❓
10. よし、ブラウザで別タブ開いて探そう❗
11. あーログインね、スマホで２段階認証して📱
12. あれ、何するんだっけ？ってことありません❓挙手🙋‍♂
13. お恥ずかしい話ですが、私はよくあります😭
14. 原因はまあ皆さんご存知の２段階認証やその他もろも ろですよね・・・・💦
15. よし、ブラウザで別タブ開いて探そう❗ 👇 新しいタブ開いて検索する🔍 👇 画面開くけど、ログイン求められる😭 👇 1password 等から情報拾ってログイン🔑 👇つづく
16. 👇 ２段階認証の通知がスマホに届く📱 👇 なんか見慣れない通知きてる❗認証だけ対応して見よ👀 👇 その結果、スマホとお友達になる🤝(youtube とか見ちゃうｗ) 👇 ついでにLINE も見ちゃう📱
17. 👇 仕事に戻る💻 👇 あれ、何するんだっけ❓
18. チーン💦
19. 今日の話はこのような事象を解決するために、私がこ うやってみたという一つのチャレンジ例です👍
20. この事象はドキュメントだけに限らず起きています が、エンジニアの皆さんはGithub は開いてますよね❓
21. 他によく使われるドキュメントって何があるか❓🤔
22. Google スライド Google スプレッドシート Google ドキュメント Notion Qiita Team Confluence
23. 自分たちは他の使ってるって方いますか❓🤔挙手🙋‍♂ Google スライド Google スプレッドシート Google ドキュメント Notion Qiita Team Confluence
24. ほぼ全部Github と別でログインするやつじゃん❓🤔 Google スライド Google スプレッドシート Google ドキュメント Notion Qiita Team Confluence
25. けど、Github にWiki とかPages ってあったよね❓🤔
26. 3️⃣ Github Pages 、Wiki とは何か
27. 3️⃣ Github Pages 、Wiki とは何か GitHub Pages とは GitHub のリポジトリから HTML 、CSS 、および JavaScript ファイル を直接取得し、任意でビルドプロセスを通 じてファイルを実行し、ウェブサイトを公開できる静的なサイトホスティングサービスです。 GitHub の github.io ドメインまたは独自のカスタム ドメインでサイトをホストできます。 ※docs.github.com より引用 テキストで説明されても・・・・・ってなりますよね💦
28. 3️⃣ Github Pages 、Wiki とは何か GitHub Pages とは
29. 3️⃣ Github Pages 、Wiki とは何か 先程のリポジトリでデプロイしたGithub Pages のサイトです
30. 3️⃣ Github Pages 、Wiki とは何か Github のWiki とは GitHub.com のすべてのリポジトリには、Wiki と呼ばれるドキュメントをホストするためのセクションが用意 されています。 リポジトリのウィキは、プロジェクトの利用方法、設計方法、中核的な原理など、プロジェク トに関する長いコンテンツを共有するために利用できます。 ※docs.github.com より引用 同じくテキストで説明されても💦
31. 3️⃣ Github Pages 、Wiki とは何か Github のWiki とは
32. しかし、Pages とWiki には長年利用されにくい問題が あった💦
33. Wiki やPages 利用時にあった問題👀 Github Pages がPublic でしか使えない💦 画像貼ったりするとURL がパブリックなURL になって危険⚡ ER 図とかなにか図形を書いて表現したいとき表現力不足💦 Markdown で書かないといけない💦 たくさん記事書くと次は検索し辛い💦
34. しかし、ついにGithub さんやその他OSS が解決してく れました👍
35. 個人的に一番助かると思ったのが、これ👇 🙌 プライベートでPages 作れる❗ 🙌
36. さらに私を助けたのがこれ👇 🙌 添付ファイルもプライベートにできる❗ 🙌
37. 次点がこれ👇 🙌 mermaid で各種の図が書ける❗ 🙌
38. そしてMarkdown で書いた文書を静的サイト化できる ツールがこれ👇 🙌 docs サイト作ればドキュメント更新もGithub 管理できる❗ 🙌
39. この４つがあればPages でドキュメントサイト構築で きそう🤔
40. ここから私はGithub Pages を使ってドキュメントを集 約してみようと思いました👍
41. 4️⃣ 結果
42. もうめんどくさいので、結果から見せてしまいます❗
43. できあがったサイトがこちら👇 https://takarashinya.github.io/docs-to-githubpages/
44. 5️⃣ Github Pages へのドキュメントの集約方法
45. 利用したツールや記法たち Markdown( 当然) 皆さんご存知の文書を記述するための軽量マークアップ言語 mdbook Markdown を用いて文書を作成できるRust 製のツール tbls CI フレンドリーなGo で書かれたデータベースドキュメントツール mermaid ダイアグラム作成およびチャート作図用のJavaScript ライブラリ plantuml UML （Unified Modeling Language ：統一モデリング言語）のダイアグラムを作成するためのオープンソ ースのツール SSGform( 問合せフォームに利用) SSGform （エスエスジーフォーム）はフォームを簡単に設置できるサービス ChatGPT(Azure OpenAI Service GPT-4 の方)
46. 6️⃣ まとめ
47. 6️⃣ まとめ Github の進化でdocs 作成と提供がしやすくなって嬉しい🙌 CI フレンドリーにER 図、テーブル定義書、システム構成図も作れて便利👍 Markdown や plantuml 、mermaid 記法は覚えないといけない💦 plantuml と mermaid はもうmermaid の勝ち❓🤔 次はコードが吐き出されるともっと良くなる(ChatGPT ではもうできる😲)
48. 👂ご静聴ありがとうございました👂