皆さん、開発してる中でドキュメントが散らかっててストレスになったり、困ったりしたこと、ありませんか❓ このトークではよくあるシステム開発プロジェクトにて発生する各種ドキュメント郡をなるべくGithub Pagesに集めてみた話をします 🦜 これらをどうやったのか、やってみてどうだったのかや面白くなってきて○○まで作ってみた的なお話ができればと思います。 レギュラートークレベルで内容が濃いかは別です^^;
システム開発におけるドキュメントをできるだけGithub Pagesに集約してみた話@takarake Hackers Champloo 2023 #hcmpl
View Slide
アジェンダ1️⃣ 自己紹介2️⃣ 今回話すこと3️⃣ Github Pages、Wikiとは何か4️⃣ 結果5️⃣ Github Pagesへのドキュメントの集約方法6️⃣ まとめ
1️⃣ 自己紹介
自己紹介(真面目用)
自己紹介(X @takarake)
自己紹介❓ではないですが、、、、
2️⃣ 今回話すこと
皆さん、業務中ドキュメントが散らかってて困ったこと、ありませんか❓
よし、ブラウザで別タブ開いて探そう❗
あーログインね、スマホで２段階認証して📱
あれ、何するんだっけ？ってことありません❓挙手🙋♂
お恥ずかしい話ですが、私はよくあります😭
原因はまあ皆さんご存知の２段階認証やその他もろもろですよね・・・・💦
よし、ブラウザで別タブ開いて探そう❗👇新しいタブ開いて検索する🔍👇画面開くけど、ログイン求められる😭👇1password等から情報拾ってログイン🔑👇つづく
👇２段階認証の通知がスマホに届く📱👇なんか見慣れない通知きてる❗認証だけ対応して見よ👀👇その結果、スマホとお友達になる🤝(youtubeとか見ちゃうｗ)👇ついでにLINEも見ちゃう📱
👇仕事に戻る💻👇あれ、何するんだっけ❓
チーン💦
今日の話はこのような事象を解決するために、私がこうやってみたという一つのチャレンジ例です👍
この事象はドキュメントだけに限らず起きていますが、エンジニアの皆さんはGithubは開いてますよね❓
他によく使われるドキュメントって何があるか❓🤔
GoogleスライドGoogleスプレッドシートGoogleドキュメントNotionQiita TeamConfluence
自分たちは他の使ってるって方いますか❓🤔挙手🙋♂GoogleスライドGoogleスプレッドシートGoogleドキュメントNotionQiita TeamConfluence
ほぼ全部Githubと別でログインするやつじゃん❓🤔GoogleスライドGoogleスプレッドシートGoogleドキュメントNotionQiita TeamConfluence
けど、GithubにWikiとかPagesってあったよね❓🤔
3️⃣ Github Pages、Wikiとは何か
3️⃣ Github Pages、Wikiとは何かGitHub PagesとはGitHubのリポジトリから HTML、CSS、および JavaScriptファイル を直接取得し、任意でビルドプロセスを通じてファイルを実行し、ウェブサイトを公開できる静的なサイトホスティングサービスです。 GitHubのgithub.ioドメインまたは独自のカスタム ドメインでサイトをホストできます。※docs.github.comより引用テキストで説明されても・・・・・ってなりますよね💦
3️⃣ Github Pages、Wikiとは何かGitHub Pagesとは
3️⃣ Github Pages、Wikiとは何か先程のリポジトリでデプロイしたGithub Pagesのサイトです
3️⃣ Github Pages、Wikiとは何かGithubのWikiとはGitHub.comのすべてのリポジトリには、Wikiと呼ばれるドキュメントをホストするためのセクションが用意されています。 リポジトリのウィキは、プロジェクトの利用方法、設計方法、中核的な原理など、プロジェクトに関する長いコンテンツを共有するために利用できます。※docs.github.comより引用同じくテキストで説明されても💦
3️⃣ Github Pages、Wikiとは何かGithubのWikiとは
しかし、PagesとWikiには長年利用されにくい問題があった💦
WikiやPages利用時にあった問題👀Github PagesがPublicでしか使えない💦画像貼ったりするとURLがパブリックなURLになって危険⚡ER図とかなにか図形を書いて表現したいとき表現力不足💦Markdownで書かないといけない💦たくさん記事書くと次は検索し辛い💦
しかし、ついにGithubさんやその他OSSが解決してくれました👍
個人的に一番助かると思ったのが、これ👇🙌 プライベートでPages作れる❗ 🙌
さらに私を助けたのがこれ👇🙌 添付ファイルもプライベートにできる❗ 🙌
次点がこれ👇🙌 mermaidで各種の図が書ける❗ 🙌
そしてMarkdownで書いた文書を静的サイト化できるツールがこれ👇🙌 docsサイト作ればドキュメント更新もGithub管理できる❗ 🙌
この４つがあればPagesでドキュメントサイト構築できそう🤔
ここから私はGithub Pagesを使ってドキュメントを集約してみようと思いました👍
4️⃣ 結果
もうめんどくさいので、結果から見せてしまいます❗
できあがったサイトがこちら👇https://takarashinya.github.io/docs-to-githubpages/
5️⃣ Github Pagesへのドキュメントの集約方法
利用したツールや記法たちMarkdown(当然)皆さんご存知の文書を記述するための軽量マークアップ言語mdbookMarkdownを用いて文書を作成できるRust製のツールtblsCIフレンドリーなGoで書かれたデータベースドキュメントツールmermaidダイアグラム作成およびチャート作図用のJavaScriptライブラリplantumlUML（Unified Modeling Language：統一モデリング言語）のダイアグラムを作成するためのオープンソースのツールSSGform(問合せフォームに利用)SSGform（エスエスジーフォーム）はフォームを簡単に設置できるサービスChatGPT(Azure OpenAI Service GPT-4の方)
6️⃣ まとめ
6️⃣ まとめGithubの進化でdocs作成と提供がしやすくなって嬉しい🙌CIフレンドリーにER図、テーブル定義書、システム構成図も作れて便利👍Markdownや plantuml、mermaid記法は覚えないといけない💦plantumlと mermaidはもうmermaidの勝ち❓🤔次はコードが吐き出されるともっと良くなる(ChatGPTではもうできる😲)
👂ご静聴ありがとうございました👂
takarashinya
peisuke
poteboy
baseballyama
takasehideki
ufried
rilmayer
lemiorhan
coconala_engineer
oracle4engineer
revcomm_inc
k1low
rynsuke
robhawkes
akmur
tanoku
paulrobertlloyd
panda_program
chriscoyier
zakiwarfel
addyosmani
dougneiner
eileencodes
lynnandtonic