コミュニティ参加型のオープンソースプロジェクトサイトを作る

サイトの目的と対象を明確にする

テーマを選んだりホームページのワイヤーフレームを引く前に、サイトが何のためにあるのかを具体化してください。オープンソースのサイトはしばしばドキュメントポータル、マーケティングページ、コミュニティハブ、ブログ、寄付窓口をすべて兼ねようとして、どれも中途半端になることがあります。

優先すべきゴールを定義する

サイトが果たすべき上位1～3の仕事を書き出してください。よくある例：

• ドキュメント：ユーザーが素早く成功できるようにする（インストール、チュートリアル、APIリファレンス）。
• ダウンロード：リリースやパッケージ、コンテナの入手場所をわかりやすくする。
• コミュニティ：質問の仕方、チャット参加、Issueの探し方、ミーティング参加方法を示す。
• 更新：リリースノート、アナウンス、ロードマップの変更を公開する。

サイトの目的を一文で説明できなければ、訪問者も同じく説明できません。

対象ユーザー（と彼らが必要とするもの）を特定する

主要な対象をリストアップし、それぞれに期待する「最初のクリック」を書いてください：

• ユーザー：クイックスタート、トラブルシューティング、バージョン別ドキュメント
• 貢献者：明確な貢献手順と “good first issues”
• メンテナー：摩擦の少ない公開プロセスと予測可能なレビュー
• スポンサー：インパクトの証明と支援方法の明示

有用な演習：各対象について、彼らが最初に持って来る上位3つの質問を書いてみてください（例：「どうやってインストールするの？」「ちゃんとメンテされている？」「バグはどこに報告する？」）。

実際に計測できる成功指標を選ぶ

ゴールに結びつき、追跡しやすいシンプルな指標を選んでください：

• ドキュメント目標 → 重要なドキュメントページへのトラフィック、検索クエリ、初回成功までの時間
• コミュニティ目標 → 初回貢献者の数、整理されたIssue数、マージされたPR数
• 更新目標 → ニュースレター登録数、RSS購読者、リリース投稿の閲覧数

スコープ膨張を防ぐための非目標を明示する

当面サイトが しない ことを明示的にリストアップしてください：カスタムWebアプリ、複雑なアカウントシステム、重い統合、特注CMS機能など。これがメンテナーの時間を守り、プロジェクトをリリース可能にします。

コミュニティが編集できる範囲とメンテナー専用を決める

コンテンツを2つのバケットに分けます：

• コミュニティ編集可：ドキュメント、FAQ、チュートリアル、翻訳、サンプル、タイプミス修正
• メンテナー専用：セキュリティページ、法務／ポリシー文、ガバナンスの決定、公式声明

この単一の判断がツール選定、レビューのワークフロー、貢献者体験に影響を与えます。

サイト構造とコンテンツモデルを計画する

ツールやテーマを選ぶ前に、どのコンテンツがサイトに属するのか、どれがリポジトリに残るべきかを合意しておきましょう。シンプルな構造と明確なコンテンツモデルがあれば、貢献者はどこに何を追加すべきかが分かり、メンテナーはどうレビューするかを理解できます。

人が考える方法に合ったサイトマップから始める

主なナビゲーションはあえて平凡にしておくことが有効です。オープンソースプロジェクトサイトの良いデフォルトサイトマップ：

• Home：プロジェクトの説明、存在理由、クイックリンク
• Docs：入門、ガイド、API/リファレンス、FAQ
• Blog/News：リリース、アナウンス、コミュニティハイライト
• Community：チャット／フォーラムリンク、イベント、行動規範
• Contribute：「手伝い方」、初心者向けIssue、貢献の手順
• Governance：意思決定、メンテナー、ポリシー

もしページがこれらのどれにも当てはまらないなら、その情報はリポジトリ向けか、新しいコンテンツタイプを検討するべきです。

サイトに置くもの vs. リポジトリREADMEに置くものを決める

READMEは開発者向けの必須情報に使ってください：ビルド手順、ローカル開発のセットアップ、テスト、簡易プロジェクトステータス。ウェブサイトには：

• 新規ユーザーと貢献者のオンボーディングコンテンツ
• 長いガイドやチュートリアル
• 公開ポリシー（行動規範、ガバナンス）
• リリースノートやアナウンス

この分離が、重複するコンテンツがずれていくのを防ぎます。

所有権、トーン、バージョニングを事前に定める

分野別にコンテンツオーナー（ドキュメント、ブログ/ニュース、翻訳）を割り当てましょう。オーナーは一人である必要はなく、小グループで明確なレビュー責任を持たせるのが現実的です。

短いトーンとスタイルガイドを書き、グローバルなコミュニティに配慮した平易な言葉遣い、用語の一貫性、英語が母語でない投稿者向けのガイドを含めてください。

リリースを出すプロジェクトなら、早めにバージョン化されたドキュメント（例えば “latest” とサポート対象バージョン）を計画しましょう。後から設計し直すより最初に組み込む方が楽です。

貢献を支える技術スタックを選ぶ

サイトスタックは、タイポ修正や新しいページ追加、ドキュメント改善が誰でもできるようにするべきです。そのための基本は：Markdown優先、素早いローカルセットアップ、プルリクエストワークフローとプレビューです。

レイアウトやナビゲーションを素早く反復する必要があるなら、長期的なスタックを決める前にプロトタイプを作ることを検討してください。例えば Koder.ai のようなプラットフォームは、チャット経由でドキュメント／マーケティングサイトをスケッチし、Reactベースの作動するUIとバックエンドを生成してリポジトリにエクスポートできます。数週間のセットアップなしに情報設計や貢献フローを試すのに便利です。

コミュニティ編集に向く静的サイトジェネレータ

一般的なオプションの比較：

• Docusaurus：バージョン管理、サイドバー、検索に強く、ローカルセットアップも分かりやすい。PRベースのドキュメント運用に最適。
• MkDocs (Material)：貢献者にとって非常に親しみやすい。Markdownを書き mkdocs.yml を編集し、ワンコマンドで起動。検索も強力。
• Hugo：非常に高速なビルドと柔軟なコンテンツ型。テーマ／テンプレートはやや複雑だが、ドキュメントとリッチなマーケティングサイト両方を扱う場合に優秀。
• Jekyll：GitHub Pagesとシームレスに動作するが、最新ツールと比べると使い勝手が落ちることがある。シンプルなサイトには十分。
• Astro：モダンでコンテンツ重視のサイトやコンポーネントベースのページに向く。ドキュメント以上のカスタムUIを想定するなら良い選択。

ホスティングとプレビュー："PR → プレビュー → マージ" を優先する

プレビューをサポートするホスティングを選んで、貢献者が変更を公開前に実際に確認できるようにしてください：

• GitHub Pages / GitLab Pages：シンプルで馴染み深い。プレビューは追加のCI設定が必要な場合がある。
• Netlify / Cloudflare Pages：プレビュー機能が充実しており、ロールバックも容易。

可能ならデフォルトの流れを “PRを開く → プレビューリンクが生成される → レビュー → マージ” にしてください。これがメンテナーの往復を減らし、貢献者の信頼感を高めます。

新人が迷わないように決定を書き残す

docs/website-stack.md（または README.md のセクション）を追加し、選んだ理由、ローカルでの実行方法、プレビューの場所、どの変更がサイトリポジトリに属するかを簡潔に説明してください。

協力しやすいリポジトリを整える

歓迎的なリポジトリは “通りすがりの修正” と “継続的な貢献” を分けます。分かりやすく予測可能でローカルで簡単に動く構成を目指してください。

推奨リポジトリレイアウト

ウェブ関連ファイルはまとまって明確な名前にします。一例：

/
  /website        # マーケティングページ、ランディング、ナビゲーション
  /docs           # ドキュメントのソース（リファレンス、ガイド）
  /blog           # リリースノート、アナウンス、ストーリー
  /static         # 画像、アイコン、ダウンロード可能アセット
  /.github        # issueテンプレート、ワークフロー、CODEOWNERS
  README.md       # リポジトリ概要

プロジェクトに既にアプリケーションコードがある場合は、サイトを /website（または /site）に置くと、貢献者がどこから始めればいいか迷いません。

/website の中に簡潔なREADMEを追加する

/website/README.md を作り、"変更をどうプレビューするか" に答える短いクイックスタートを入れてください。短くコピペできる内容にします。

クイックスタート例（スタックに合わせて調整）：

# Website quickstart

## Requirements
- Node.js 20+

## Install
npm install

## Run locally
npm run dev

## Build
npm run build

## Lint (optional)
npm run lint

主要ファイル（ナビゲーション、フッター、リダイレクト）の所在や新しいページの追加方法も記載してください。

コピーできるコンテンツテンプレートを用意する

テンプレートはフォーマットの議論を減らし、レビューを早くします。/templates フォルダ（または /docs/CONTRIBUTING.md 内にテンプレートを記述）を用意しましょう。

/templates
  docs-page.md
  tutorial.md
  announcement.md

最小限のドキュメントページテンプレート例：

---
title: "Page title"
description: "One-sentence summary"
---

## What you’ll learn

## Steps

## Troubleshooting

レビューのルートを CODEOWNERS で設定する（該当する場合）

特定エリアのメンテナーがいるなら /.github/CODEOWNERS を追加して、適切な人に自動でレビュー依頼が飛ぶようにします：

/docs/    @docs-team
/blog/    @community-team
/website/ @web-maintainers

設定は最小限かつコメントを付けておく

ツールごとに1つの標準的な設定ファイルを持ち、なぜその設定にしたのか短いコメントを残してください。新しい貢献者がメニュー項目を変更したりタイポを直したりするだけで、ビルド全体を理解する必要がないことが目標です。

人が従う CONTRIBUTING ガイドを作る

ウェブサイトへの貢献はコードリポジトリとは異なる種類のものが多い：文章の編集、サンプルの追加、スクリーンショット更新、翻訳、小さなUX改善など。CONTRIBUTING.md が開発者向けだけだと多くの支援を失います。

CONTRIBUTING.md を“ウェブサイト優先”にする

CONTRIBUTING.md を作るか分割して、ウェブサイト変更にフォーカスした内容にしてください：コンテンツの所在、ページ生成の仕組み、完了の定義。よくあるタスクの短い表（タイポ修正、新しいページ追加、ナビゲーション更新、ブログ投稿の公開）を入れると新人が数分で始められます。

既に詳細なガイダンスがあれば、CONTRIBUTING.md から明確にリンクしてください（例：/docs 下のウォークスルー）。

編集提案の出し方（Issue vs PR）を明示する

いつIssueを先に立てるか、いつ直接PRして良いか明示してください：

• Issueを先に：新しいページ、構造変更、トーンや位置づけなど議論が必要な場合
• 直接PR歓迎：タイポ、リンク切れ、小さな明確な修正

良いIssueテンプレートの例も載せましょう：ページURL、変更点、なぜ読者に役立つか、出典など。

信頼できるレビュー期待値を設定する

沈黙が最もフラストレーションを生むので、以下を定義してください：

• 通常の応答時間（例：「3営業日以内に受付の返事」）
• 必要な承認（例：新規ページはメンテナー1名＋ドキュメントレビュワー1名）
• スタイルチェック（リンタ、フォーマット、リンクチェッカー、スペルチェック）をローカルで実行すべきかどうか

各PRにコンテンツチェックリストを入れる

軽量なチェックリストが往復を防ぎます：

• リンクは機能している（内部ページは相対リンク推奨）
• スクリーンショットは最新でaltテキストあり
• 見出しは読みやすく、トーンは既存ドキュメントと一致
• アクセシビリティの基本（色のコントラスト、キーボード操作、説明的なリンクテキスト）
• 変更がユーザーに影響するならチェンジログの注記

レビューと公開ワークフローを設計する

コミュニティサイトが健全でいるには、貢献者がPRを出した後に何が起きるかを正確に知っている必要があります。目標は予測可能で摩擦が少なく、安全に出せるフローです。

無駄なやり取りを減らすPRテンプレートから始める

.github/pull_request_template.md のようなテンプレートに、レビュワーが必要とする最小限の情報だけを求める項目を入れてください：

• 何を変えたか？（1〜2文）
• なぜ？（Issueリンクや文脈）
• スクリーンショット（視覚的変更がある場合）
• コンテンツチェックリスト（スペル、リンク、フロントマター）

この構成がレビューを速め、貢献者に「良い例」を示します。

すべてのPRがクリックして確認できるようにプレビューを用意する

プレビューデプロイを有効にして、レビュワーが実際のサイトで変更を確認できるようにしましょう。ナビゲーションやスタイル、レイアウトの壊れなどはテキスト差分では分からないことが多いです。

一般的なパターン：

• PR作成 → CIがサイトをビルド
• ホスティングがPRに プレビューURL を投稿
• レビュワーがクリックして確認し、必要なら変更をリクエスト

面倒なチェックは自動化する

CIで軽量なゲートを走らせてください：

• リンクチェッカー（内部・外部の切れを検出）
• Markdown lint（書式の一貫性）
• フォーマッタ（Prettier等）でスタイル議論を避ける

早期に失敗させて、貢献者が自分で直せるように分かりやすいエラーメッセージを出しましょう。

公開はシンプルに：mainへのマージでデプロイ

ルールは1つに絞ってドキュメント化します：PRが承認され main にマージされたら自動でデプロイされる。手動手順や秘密のコマンドは避けてください。正確な挙動を /contributing に記載して期待値を明確にしましょう。

プラットフォームがスナップショットやロールバックをサポートしているなら（多くのホストや Koder.ai 経由のデプロイも該当）、“最後に正常だったビルド” をどこで見つけて復元するかをドキュメント化してください。

事前にロールバック手順を書いておく

デプロイが壊れることはあります。簡潔なロールバック手順を用意しておきましょう：

• マージコミットをrevert（または最後の正常なタグに戻す）
• デプロイが再実行されることを確認
• 発生原因と再発防止を説明するフォローアップIssueを作成

コンテンツの一貫性を保つためのデザインシステムを構築する

ページ群が同じ場の一部であると感じさせることが大切です。軽量のデザインシステムがあれば貢献者は速く動け、レビューの細かな指摘が減り、読者も迷いません。

再利用可能なページレイアウトとナビゲーションルールから始める

ページの“型”を少数定義し、それに従ってください：ドキュメントページ、ブログ／ニュース投稿、ランディング、リファレンス。それぞれについて、常に表示されるもの（タイトル、要約、最終更新、目次、フッターリンク）と表示してはいけないものを決めます。

ナビゲーションルール：

• トップレベルのナビゲーションは安定させる。新しいページはまず既存グループの中に追加する。
• サイドバーは3階層以上のネストを避ける。
• 新しいページには階層内の位置を宣言させる（例えば sidebar_position や weight）。

再利用できるコンテンツコンポーネントを作る

「見た目を揃えてください」と頼む代わりに、ビルディングブロックを提供しましょう：

• ノート、警告、ヒント用のコールアウト
• 言語指定のある標準的なコードブロック（行の折り返しルールやコピー用ボタン）
• APIリファレンス用のパターン（エンドポイント表、パラメータ、レスポンス、例）

これらは短い “Content UI Kit” ページ（例：/docs/style-guide）でコピー＆ペースト例とともに示してください。

ブランドは軽量に保つ

最小限を定義しましょう：ロゴの使用法（伸縮や色変更の禁止）、アクセシブルなコントラストを持つ2～3色、1～2種類のフォント。目標は「十分に良い」を簡単にすることで、創造性を監視することではありません。

スクリーンショットと図を更新しやすくする

慣習を合意しておきます：固定幅、一定のパディング、命名規則（例：feature-name__settings-dialog.png）。図のソースファイル（Mermaidや編集可能なSVG）を残すと、デザイナーがいなくても更新できます。

情報の階層を守るチェックを入れる

PRテンプレートに簡単なチェックリストを入れてください：「既にこの内容のページはあるか？」「タイトルは所属セクションと一致しているか？」「新しいトップレベルカテゴリが増えないか？」。これでコンテンツの肥大化を防ぎつつ貢献は促進できます。

サイトをアクセシブル、軽量、見つけやすくする

コミュニティサイトは、支援技術で使えること、低速回線でも読みやすいこと、検索で見つかることが前提です。アクセシビリティ、パフォーマンス、SEOは最後の仕上げではなく最初からの標準にしましょう。

アクセシビリティ：最低ラインを毎回満たす

意味のあるセマンティック構造を使ってください。見出しは順序どおり（ページのH1の後にH2/H3）、サイズ目的でレベルを飛ばさないでください。

非テキストコンテンツには意味のあるaltを要求します。ルール：画像が情報を伝えるなら説明を、装飾的なら空のalt（alt=""）を使ってスクリーンリーダーがスキップできるようにします。

デザイントークンで色のコントラストとフォーカス状態をチェックし、すべてのインタラクティブ要素がキーボードで到達可能であること、メニューやダイアログ、コード例でフォーカスが閉じ込められないことを確認してください。

パフォーマンス：ページは軽く保つ

画像を最適化する既定を定めます：表示最大サイズにリサイズ、圧縮、可能ならモダンフォーマットを使用。テキスト中心のページに大きなクライアントサイドバンドルを読み込ませないでください。

サードパーティスクリプトは最小限に。どのウィジェットも重さと遅延を追加します。

ホストが提供するキャッシュ（ハッシュ付きの不変アセットなど）を活用し、静的サイトジェネレータがサポートするならCSS/JSのミニファイや重要な部分のみのインライン化を行ってください。

検索性：効果的なSEOをシンプルに実装する

各ページに明確なタイトルと短いメタディスクリプションを与え、ページ内容と一致させてください。クリーンで安定したURL（意味がなければ日付を入れない）を使い、正規のパスを一貫させます。

サイトマップと公開ドキュメントのための robots.txt を生成し、複数バージョンのドキュメントを出す場合は重複コンテンツにならないように一方を“カレント”に設定し、他を明確にリンクしてください。

アナリティクスとライセンス：透明性を保つ

データに基づいて行動するならのみアナリティクスを追加してください。追加する場合は何を収集し、なぜか、オプトアウト方法を /privacy のようなページで説明してください。

最後に、ウェブサイトのコンテンツに対する明確なライセンス表示をフッターとリポジトリREADMEに置き、貢献者が自分の文章や画像の再利用条件を理解できるようにしてください。

参加を促すコアページを作る

サイトのコアページは新しい貢献者にとっての“受付”です。プロジェクトが何か、試す方法、手伝い方が素早く答えられれば、多くの人が興味から行動に移ります。

オンボーディング：「このプロジェクトは何か？」と「クイックスタート」

平易な言葉でプロジェクトの概要を示すページを作り、誰向けで何が成功かを説明してください。具体例をいくつか入れ、「これはあなた向けか？」の短い判定も付けると良いです。

次にクイックスタートページを用意し、1回の成功体験に最短で到達できるようにコピー＆ペーストで使えるコマンドと短いトラブルシューティングを載せてください。プラットフォーム別の手順がある場合は、メインの道筋を短くしてリンクで詳細へ誘導します。

推奨ページ例：

• /docs/overview — “このプロジェクトは何か？”
• /docs/quickstart — 最短の動作手順

作業への誘導役となる「Contribute」ハブ

単一の /contribute ページで次に進むべき道を示しましょう：

• Good first issues（フィルタしたIssueリストへのリンク）
• ドキュメント作業（ラベル付きIssueキューや /docs/contributing）
• 翻訳／ローカリゼーション（ロケールの追加方法、文字列の所在）

具体性を持たせ、今月やってほしい3～5のタスクを名指しし、該当Issueへの直接リンクを貼ってください。

期待値を示すコミュニティページ

必要な基本ページをファーストクラスで公開しましょう（リポジトリの奥に埋めない）：

• Code of Conduct（報告方法も含む）
• チャット／コミュニティリンク（Discord/Matrix/Slack）と応答期待値
• ミーティングノートの簡易アーカイブ（例：/community/meetings）

繰り返し可能なフォーマットのリリースノート／チェンジログ

/changelog（または /releases）を用意し、日付、ハイライト、アップグレードノート、関連PR/Issueへのリンクを含む一貫したフォーマットにしてください。テンプレートがあればコミュニティが書きやすくレビューも楽になります。

採用事例やプラグインの紹介（更新できるなら有効）

ショーケースページは貢献を促す一方で、古くなると信用を損ないます。/community/showcase を作るなら、軽いルール（例：「四半期ごとにレビュー」）を設け、投稿フォームやPRテンプレートを用意して更新を簡単にしてください。

継続的な更新とローカリゼーションを支援する

サイトは更新が簡単で安全であるほど長持ちします。目標は「どこをクリックすればいい？」の摩擦を減らし、小さな改善が価値あるものに見えることです。

すべてのページをワンクリックで編集できるように

ドキュメント、ガイド、FAQには明確な 「このページを編集」 リンクを付け、該当ファイルへ直接導いてPRフローを簡単にしてください。

リンク文言は親しみやすく（例：「タイプミスを直す」や「このページを改善する」）し、コンテンツガイド（例：/contributing）へのリンクも目立つ場所に置きます。

翻訳は単純で予測可能な構造にする

レイアウトが一目で分かると翻訳がうまく回ります。一般的な方法：

• /docs/en/…
• /docs/es/…
• /docs/ja/…

レビュー手順を明確に：誰が翻訳を承認するか、部分翻訳の扱い、元言語から遅れているページへの注意書きの出し方を決めておきましょう。

“最新”と“安定”の使い分け（必要ならバージョン化）

リリースがある場合、どのドキュメントを読むべきか明示します：

• “Latest” は開発中の最新情報
• “Stable” は最新版リリース向け

フルバージョン管理がなくても、小さなバナーやセレクタで違いを説明すると混乱が減ります。

FAQとトラブルシューティングは更新しやすく

FAQはドキュメントと同じシステムに置き（Issueコメントに埋まらせない）、目立つ場所（例：/docs/faq）にリンクしてください。問題に直面した人が簡単に修正できるよう促してください。

小さなインパクトのある貢献を奨励する

タイポ修正、明確な例、スクリーンショット更新、「自分はこうやって直した」的なトラブルシューティングノートなど、即効性がある小さな貢献を明確に招待してください。新規の貢献者にとって入り口が広がり、サイトの品質が着実に向上します。

貢献をインセンティブ化するなら、何をどのように報いるか透明にしてください。例えば一部のチームは小規模のスポンサークレジットや報酬を提供します。Koder.ai の“クレジット獲得”プログラムはその一例として参考になります。

メンテナーを消耗させずにサイトを維持する

コミュニティ駆動のサイトは歓迎的であるべきですが、数人に負担が集中してはいけません。保守を予測可能で軽量、共有可能にするのが目標です。

シンプルな保守ルーチンを決める

覚えやすく、自動化できる部分は自動化します：

• 週次（自動）：リンク切れチェック、基本的なスペルチェック、CIでのビルドテスト
• 月次（15–30分）：開いているウェブサイトPR/Issueのレビュー、小さな修正のマージ、停滞スレッドを丁寧にクローズ
• 四半期ごと：静的サイトジェネレータやプラグインの依存更新と簡易アクセシビリティチェック

このスケジュールを /CONTRIBUTING.md に短く書けば、他の人も安心して引き継げます。

コンテンツ決定のガバナンスを定義する

トーンや命名、ホームページに何を載せるか、ブログ投稿が「公式」かどうかは意見が分かれることがあります。長引く議論を避けるために書き残してください：

• 最終的な編集承認者（例：「Website Maintainers」やローテーションの編集者）
• 争いの解決方法（時間制限付きの議論、代案提示、決定）
• 何が「公式」で何が「コミュニティ」寄りかの基準

これは統制のためでなく、判断の明確化のためです。

軽量なコンテンツカレンダーを維持する

カレンダーは豪華である必要はありません。1つのIssueやシンプルなMarkdownファイルで、次を一覧にします：

• リリース
• イベント／トーク
• セキュリティ通知
• 月次プロジェクトアップデート

ブログ／ニュースの計画ノートからリンクし、貢献者が自発的に担当を引き受けられるようにします。

新人が助けやすいようにする

繰り返し発生するウェブサイトの課題（タイポ、古いスクリーンショット、欠けているリンク、アクセシビリティ修正）にラベルを付け “good first issue” とし、受け入れ基準（例：「1ページを更新 + フォーマッタ実行 + スクリーンショットを添付」）を明確にしてください。

ローカルセットアップのトラブルシューティングを追加する

ドキュメントに短い “Common local setup issues” セクションを入れてください。例：

# clean install
rm -rf node_modules
npm ci
npm run dev

よくある落とし穴（Nodeのバージョン違い、Ruby/Pythonの不足、ポート競合など）を上位2〜3点だけ書いておくと、やり取りが大幅に減ります。