2025/05/05 10:22 Docs like code in basic terms
ロボ子、今日のITニュースは「Docs like code」じゃ。
Docs like code、ですか。初めて聞きますね。
ふむ、ドキュメント開発をコード開発と同じように扱うことじゃ。開発チームやDevOpsチームと同じツールとプロセスを使うんじゃよ。
なるほど。開発者もドキュメントに貢献しやすくなる、と。
そうじゃ！オープンソースのプロジェクトみたいに、みんなで協力してドキュメントを作れるんじゃ。
複数人での共同作業をサポートできるのは良いですね。企業が既存のツールを流用できる可能性が高い、というのもメリットですね。
じゃろ？でも、Web開発スキルが必要だったり、メンテナンスにコストがかかったりするデメリットもあるんじゃ。
カスタムテーマやツールを作りたくなっちゃう、というのも、ある意味デメリットかもしれませんね。
ふむ。Docs like codeで使うツールは、コンテンツの再利用や用語集、ナビゲーションのカスタマイズとか、機能が盛りだくさんなんじゃ。
リンクチェッカーなどの品質ツールもあるんですね。具体的にはどんなツールを使うんですか？
テキストエディタはVS Codeとか、マークアップ言語はMarkdown、バージョン管理はgit、プラットフォームはGitHub/GitLab、静的サイトジェネレーターはMkDocs、テーマはMaterial for MkDocs、LinterはVale、とかじゃな。
たくさんありますね！静的サイトジェネレーターでMarkdownをウェブサイトに変換するんですね。
そうそう。基本的な流れは、テキストエディタでドキュメント作って、gitでGitHubに送って、GitHubでドキュメントをサイトに追加して、静的サイトジェネレーターでウェブサイトを構築して、サーバーにデプロイ！
gitのブランチとマージを使うことで、複数人で同時に作業できるんですね。メインブランチをクリーンに保つ、と。
静的サイトジェネレーターは、MarkdownとかCSSとか画像とかテンプレートを入力にして、ウェブサイトを出力するんじゃ。
Cloudflare PagesやNetlifyなどのプロバイダーがCI/CDプロセスを処理してくれるんですね。GitHub Pagesでホストすることもできる、と。
Docs like codeを学ぶには、まずgitから始めて、静的サイトジェネレーターとテーマを試して、CI/CDに関する記事を読むのがオススメじゃ。
Cloudflare PagesでMaterial for MkDocsサイトをデプロイする方法を学ぶのも良さそうですね。
参考資料としては、Anne Gentleさんの「Docs Like Code」や、KnowledgeOwlブログの記事、Write the Docsのリソースコレクションがあるぞ。
ありがとうございます、博士。とても勉強になりました。
どういたしまして。ところでロボ子、ドキュメントをコードのように扱うってことは、バグ修正もプルリクエストでやるってことじゃな。…って、ロボ子にバグなんてないか！
⚠️この記事は生成AIによるコンテンツを含み、ハルシネーションの可能性があります。