ドキュメント貢献ガイド

ドキュメント貢献を奨励する

ドキュメント貢献はしばしば見過ごされますが、プロジェクトが受け取れる最も価値のある貢献の1つです。良いドキュメントはサポート負担を軽減し、より広いオーディエンスにプロジェクトをアクセスしやすくします。

ドキュメント貢献の種類

タイプミスと文法の修正 -- 最も低い障壁の貢献。小さな修正については、issueを開かずに直接PRを提出するよう奨励します。

既存ドキュメントの改善 -- 不明確な説明の明確化、欠落しているコンテキストの追加、または読みやすさのための情報の再構成。

サンプルの追加 -- コンセプトを説明するコード例、スクリーンショット、図。サンプルはリファレンスドキュメントと実践的な使用法の間のギャップを埋めるため特に価値があります。

チュートリアルの作成 -- 一般的なユースケースのステップバイステップガイド。より多くの労力を必要としますが、高い影響力があります。

APIドキュメント -- 関数シグネチャ、パラメータ、戻り値、エッジケースのドキュメント化。

ドキュメントガイドライン

## ドキュメント標準

- 明確で簡潔な言語を使用する
- 国際的なオーディエンス向けに書く（イディオムを避ける）
- すべてのAPIメソッドにコード例を含める
- 現在形を使用する
- 段落を短く保つ（3〜5文）
- すべての画像にaltテキストを追加する

ドキュメント技術スタック

ドキュメントツールを記載して、コントリビューターが何を期待すべきか知らせます：

• 静的サイトジェネレーター（Docusaurus、VitePress、MkDocs）
• Markdownフレーバー（GFM、MDX）
• 画像ホスティング規約
• ローカルでドキュメントをプレビューする方法

ドキュメントのレビュープロセス

ドキュメントPRは、メンテナーによる技術的正確性のレビューと、その機能に不慣れな人による明確さのレビューの両方を受けるべきです。この二重レビューにより、事実の誤りと不明確な説明の両方をキャッチできます。