コミュニティの貢献を受け入れるワークフロー、レビュー手順、確実な公開方法を備えたオープンソースのプロジェクトサイトの計画、構築、維持方法を学びます。

テーマを選んだりホームページのワイヤーフレームを引く前に、サイトが何のためにあるのかを具体化してください。オープンソースのサイトはしばしばドキュメントポータル、マーケティングページ、コミュニティハブ、ブログ、寄付窓口をすべて兼ねようとして、どれも中途半端になることがあります。
サイトが果たすべき上位1~3の仕事を書き出してください。よくある例:
サイトの目的を一文で説明できなければ、訪問者も同じく説明できません。
主要な対象をリストアップし、それぞれに期待する「最初のクリック」を書いてください:
有用な演習:各対象について、彼らが最初に持って来る上位3つの質問を書いてみてください(例:「どうやってインストールするの?」「ちゃんとメンテされている?」「バグはどこに報告する?」)。
ゴールに結びつき、追跡しやすいシンプルな指標を選んでください:
当面サイトが しない ことを明示的にリストアップしてください:カスタムWebアプリ、複雑なアカウントシステム、重い統合、特注CMS機能など。これがメンテナーの時間を守り、プロジェクトをリリース可能にします。
コンテンツを2つのバケットに分けます:
この単一の判断がツール選定、レビューのワークフロー、貢献者体験に影響を与えます。
ツールやテーマを選ぶ前に、どのコンテンツがサイトに属するのか、どれがリポジトリに残るべきかを合意しておきましょう。シンプルな構造と明確なコンテンツモデルがあれば、貢献者はどこに何を追加すべきかが分かり、メンテナーはどうレビューするかを理解できます。
主なナビゲーションはあえて平凡にしておくことが有効です。オープンソースプロジェクトサイトの良いデフォルトサイトマップ:
もしページがこれらのどれにも当てはまらないなら、その情報はリポジトリ向けか、新しいコンテンツタイプを検討するべきです。
READMEは開発者向けの必須情報に使ってください:ビルド手順、ローカル開発のセットアップ、テスト、簡易プロジェクトステータス。ウェブサイトには:
この分離が、重複するコンテンツがずれていくのを防ぎます。
分野別にコンテンツオーナー(ドキュメント、ブログ/ニュース、翻訳)を割り当てましょう。オーナーは一人である必要はなく、小グループで明確なレビュー責任を持たせるのが現実的です。
短いトーンとスタイルガイドを書き、グローバルなコミュニティに配慮した平易な言葉遣い、用語の一貫性、英語が母語でない投稿者向けのガイドを含めてください。
リリースを出すプロジェクトなら、早めにバージョン化されたドキュメント(例えば “latest” とサポート対象バージョン)を計画しましょう。後から設計し直すより最初に組み込む方が楽です。
サイトスタックは、タイポ修正や新しいページ追加、ドキュメント改善が誰でもできるようにするべきです。そのための基本は:Markdown優先、素早いローカルセットアップ、プルリクエストワークフローとプレビューです。
レイアウトやナビゲーションを素早く反復する必要があるなら、長期的なスタックを決める前にプロトタイプを作ることを検討してください。例えば Koder.ai のようなプラットフォームは、チャット経由でドキュメント/マーケティングサイトをスケッチし、Reactベースの作動するUIとバックエンドを生成してリポジトリにエクスポートできます。数週間のセットアップなしに情報設計や貢献フローを試すのに便利です。
一般的なオプションの比較:
mkdocs.yml を編集し、ワンコマンドで起動。検索も強力。プレビューをサポートするホスティングを選んで、貢献者が変更を公開前に実際に確認できるようにしてください:
可能ならデフォルトの流れを “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
特定エリアのメンテナーがいるなら /.github/CODEOWNERS を追加して、適切な人に自動でレビュー依頼が飛ぶようにします:
/docs/ @docs-team
/blog/ @community-team
/website/ @web-maintainers
ツールごとに1つの標準的な設定ファイルを持ち、なぜその設定にしたのか短いコメントを残してください。新しい貢献者がメニュー項目を変更したりタイポを直したりするだけで、ビルド全体を理解する必要がないことが目標です。
ウェブサイトへの貢献はコードリポジトリとは異なる種類のものが多い:文章の編集、サンプルの追加、スクリーンショット更新、翻訳、小さなUX改善など。CONTRIBUTING.md が開発者向けだけだと多くの支援を失います。
CONTRIBUTING.md を作るか分割して、ウェブサイト変更にフォーカスした内容にしてください:コンテンツの所在、ページ生成の仕組み、完了の定義。よくあるタスクの短い表(タイポ修正、新しいページ追加、ナビゲーション更新、ブログ投稿の公開)を入れると新人が数分で始められます。
既に詳細なガイダンスがあれば、CONTRIBUTING.md から明確にリンクしてください(例:/docs 下のウォークスルー)。
いつIssueを先に立てるか、いつ直接PRして良いか明示してください:
良いIssueテンプレートの例も載せましょう:ページURL、変更点、なぜ読者に役立つか、出典など。
沈黙が最もフラストレーションを生むので、以下を定義してください:
軽量なチェックリストが往復を防ぎます:
コミュニティサイトが健全でいるには、貢献者がPRを出した後に何が起きるかを正確に知っている必要があります。目標は予測可能で摩擦が少なく、安全に出せるフローです。
.github/pull_request_template.md のようなテンプレートに、レビュワーが必要とする最小限の情報だけを求める項目を入れてください:
この構成がレビューを速め、貢献者に「良い例」を示します。
プレビューデプロイを有効にして、レビュワーが実際のサイトで変更を確認できるようにしましょう。ナビゲーションやスタイル、レイアウトの壊れなどはテキスト差分では分からないことが多いです。
一般的なパターン:
CIで軽量なゲートを走らせてください:
早期に失敗させて、貢献者が自分で直せるように分かりやすいエラーメッセージを出しましょう。
mainへのマージでデプロイルールは1つに絞ってドキュメント化します:PRが承認され main にマージされたら自動でデプロイされる。手動手順や秘密のコマンドは避けてください。正確な挙動を /contributing に記載して期待値を明確にしましょう。
プラットフォームがスナップショットやロールバックをサポートしているなら(多くのホストや Koder.ai 経由のデプロイも該当)、“最後に正常だったビルド” をどこで見つけて復元するかをドキュメント化してください。
デプロイが壊れることはあります。簡潔なロールバック手順を用意しておきましょう:
ページ群が同じ場の一部であると感じさせることが大切です。軽量のデザインシステムがあれば貢献者は速く動け、レビューの細かな指摘が減り、読者も迷いません。
ページの“型”を少数定義し、それに従ってください:ドキュメントページ、ブログ/ニュース投稿、ランディング、リファレンス。それぞれについて、常に表示されるもの(タイトル、要約、最終更新、目次、フッターリンク)と表示してはいけないものを決めます。
ナビゲーションルール:
sidebar_position や weight)。「見た目を揃えてください」と頼む代わりに、ビルディングブロックを提供しましょう:
これらは短い “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のミニファイや重要な部分のみのインライン化を行ってください。
各ページに明確なタイトルと短いメタディスクリプションを与え、ページ内容と一致させてください。クリーンで安定したURL(意味がなければ日付を入れない)を使い、正規のパスを一貫させます。
サイトマップと公開ドキュメントのための robots.txt を生成し、複数バージョンのドキュメントを出す場合は重複コンテンツにならないように一方を“カレント”に設定し、他を明確にリンクしてください。
データに基づいて行動するならのみアナリティクスを追加してください。追加する場合は何を収集し、なぜか、オプトアウト方法を /privacy のようなページで説明してください。
最後に、ウェブサイトのコンテンツに対する明確なライセンス表示をフッターとリポジトリREADMEに置き、貢献者が自分の文章や画像の再利用条件を理解できるようにしてください。
サイトのコアページは新しい貢献者にとっての“受付”です。プロジェクトが何か、試す方法、手伝い方が素早く答えられれば、多くの人が興味から行動に移ります。
平易な言葉でプロジェクトの概要を示すページを作り、誰向けで何が成功かを説明してください。具体例をいくつか入れ、「これはあなた向けか?」の短い判定も付けると良いです。
次にクイックスタートページを用意し、1回の成功体験に最短で到達できるようにコピー&ペーストで使えるコマンドと短いトラブルシューティングを載せてください。プラットフォーム別の手順がある場合は、メインの道筋を短くしてリンクで詳細へ誘導します。
推奨ページ例:
単一の /contribute ページで次に進むべき道を示しましょう:
/docs/contributing)具体性を持たせ、今月やってほしい3~5のタスクを名指しし、該当Issueへの直接リンクを貼ってください。
必要な基本ページをファーストクラスで公開しましょう(リポジトリの奥に埋めない):
/community/meetings)/changelog(または /releases)を用意し、日付、ハイライト、アップグレードノート、関連PR/Issueへのリンクを含む一貫したフォーマットにしてください。テンプレートがあればコミュニティが書きやすくレビューも楽になります。
ショーケースページは貢献を促す一方で、古くなると信用を損ないます。/community/showcase を作るなら、軽いルール(例:「四半期ごとにレビュー」)を設け、投稿フォームやPRテンプレートを用意して更新を簡単にしてください。
サイトは更新が簡単で安全であるほど長持ちします。目標は「どこをクリックすればいい?」の摩擦を減らし、小さな改善が価値あるものに見えることです。
ドキュメント、ガイド、FAQには明確な 「このページを編集」 リンクを付け、該当ファイルへ直接導いてPRフローを簡単にしてください。
リンク文言は親しみやすく(例:「タイプミスを直す」や「このページを改善する」)し、コンテンツガイド(例:/contributing)へのリンクも目立つ場所に置きます。
レイアウトが一目で分かると翻訳がうまく回ります。一般的な方法:
レビュー手順を明確に:誰が翻訳を承認するか、部分翻訳の扱い、元言語から遅れているページへの注意書きの出し方を決めておきましょう。
リリースがある場合、どのドキュメントを読むべきか明示します:
フルバージョン管理がなくても、小さなバナーやセレクタで違いを説明すると混乱が減ります。
FAQはドキュメントと同じシステムに置き(Issueコメントに埋まらせない)、目立つ場所(例:/docs/faq)にリンクしてください。問題に直面した人が簡単に修正できるよう促してください。
タイポ修正、明確な例、スクリーンショット更新、「自分はこうやって直した」的なトラブルシューティングノートなど、即効性がある小さな貢献を明確に招待してください。新規の貢献者にとって入り口が広がり、サイトの品質が着実に向上します。
貢献をインセンティブ化するなら、何をどのように報いるか透明にしてください。例えば一部のチームは小規模のスポンサークレジットや報酬を提供します。Koder.ai の“クレジット獲得”プログラムはその一例として参考になります。
コミュニティ駆動のサイトは歓迎的であるべきですが、数人に負担が集中してはいけません。保守を予測可能で軽量、共有可能にするのが目標です。
覚えやすく、自動化できる部分は自動化します:
このスケジュールを /CONTRIBUTING.md に短く書けば、他の人も安心して引き継げます。
トーンや命名、ホームページに何を載せるか、ブログ投稿が「公式」かどうかは意見が分かれることがあります。長引く議論を避けるために書き残してください:
これは統制のためでなく、判断の明確化のためです。
カレンダーは豪華である必要はありません。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点だけ書いておくと、やり取りが大幅に減ります。
一文の目的ステートメントを書き、その後サイトが達成すべき上位1~3の役割を列挙してください(例:ドキュメント、ダウンロード、コミュニティ、更新)。
ページや機能がそれらの役割を支援しないなら、その項目は当面の非目標として扱いましょう。
簡単なチェック:サイトの目的を一文で説明できなければ、訪問者も説明できません。
主要な対象ユーザーを列挙し、それぞれに対して期待する「最初のクリック」を定義します:
各対象について彼らが持って来る上位3つの質問(例:「これってメンテナンスされている?」「バグはどこに報告する?」)を書き出し、ナビゲーションが素早くそれに答えるようにしてください。
人が探す方法に合わせて“あえて地味に”したサイトマップから始めましょう:
新しいコンテンツがこれらに当てはまらない場合、それは新しいコンテンツタイプが必要か、その情報はリポジトリに置くべきであることを示すサインです。
READMEは開発者向けのワークフローに使い、公開向けのオンボーディングはウェブサイトに置きます。
リポジトリREADMEには:
ウェブサイトには:
これにより重複したコンテンツがずれていくのを防げます。
Markdown中心の編集と素早いローカルプレビューをサポートするスタックを選んでください。
よく使われる選択肢:
標準的な流れを PR → プレビュー → レビュー → マージ にすると良いです。
実践的には:
mainにマージでデプロイ)これでレビュープロセスの往復を減らし、貢献者に安心感を与えます。
構造とテンプレートでフォーマットの議論を減らしてください。
有用な基本:
/website, , , のような明確なレイアウト“ウェブサイト中心”で具体的な CONTRIBUTING.md を用意してください。
含めるべき項目:
短くして実際に読まれるようにし、詳細は別ドキュメントへリンクしてください。
これらはオプションの仕上げではなく初期からの前提にしてください:
可能なら自動チェック(リンクチェッカー、Markdown lint、フォーマッタ)を導入し、レビューの手間を減らしましょう。
更新を簡単に、メンテナンスを予測可能にします。
コミュニティ更新のために:
/docs/faq)/docs/en/..., /docs/es/... のように決まった構造にするメンテナの負担軽減のために:
今日のニーズを満たす最も単純なツールを選ぶのが鉄則です。
/docs/blog/.github/website/README.md にコピペできるローカル起動コマンド/templates フォルダ(docsページ、チュートリアル、アナウンス)CODEOWNERS目標は、誰でもタイポ修正やページ追加ができることです。
/privacy を用意して収集内容と目的を明示する