GitHub Docs のベストプラクティス

GitHub ドキュメントについて

GitHub では、正確で価値があり、包括的で、アクセシビリティが高く、使いやすいドキュメントを作成するよう努めています。

GitHub Docs に寄稿する前に、GitHub のドキュメントの理念とコンテンツ設計の原則について理解しておいてください。

新しい記事を作成する場合でも、既存の記事を更新する場合でも、GitHub Docs を記述するときは、次のガイドラインに従う必要があります。

始める前に、読者は誰か、読者の目標、記事が取り組む主要なタスクや概念、記述するコンテンツのタイプを理解することが重要です。

意図する読者とコンテンツの主要な目的に基づいて、記述するコンテンツのタイプを決定します。 GitHub Docs では、次のコンテンツタイプを使用します。

たとえば、概念的コンテンツタイプを使用すると、読者が機能またはトピックの基本と、読者が目標を達成するのにどのように役立つかを理解するのに役立ちます。手続き型コンテンツタイプを使用すると、ユーザーが特定のタスクを最初から最後まで完了するのに役立ちます。

コンテンツを構成するには、次のベストプラクティスを使用します。既存の記事にコンテンツを追加するときは、可能な限り既存の構造に従ってください。

初期コンテキストを指定します。トピックを定義し、読者との関連性を示します。
重要度と関連性によって論理的な順序でコンテンツを構成します。優先度の順に情報を配置し、ユーザーが必要とする順序で情報を配置します。
長い文や段落を避けます。
- 概念は 1 つずつ紹介します。
- 1 つの段落で使用するアイデアは 1 つにします。
- 1 つの文で使用するアイデアは 1 つにします。
最も重要な情報を強調します。
- 最も重要な単語とポイントで各文または段落を開始します。
- 概念を説明する場合は、最初に結論を書き、それから詳しく説明します。 (これは「逆ピラミッド」と呼ばれることもあります)。
- 複雑なトピックについて説明する場合は、まず読者に基本情報を提示し、記事の後半で詳細を開示します。
意味のある小見出しを使用します。関連する段落をセクションに整理します。各セクションに、コンテンツを正確に記述する一意の小見出しを付けます。
長いコンテンツにはページ内リンクを使用することを検討します。これにより、読者は関心のある分野にジャンプし、無関係なコンテンツをスキップできます。

忙しいユーザーがテキストを読んで理解しやすくします。

簡単な言葉を使用します。 一般的で日常的な単語を使用し、可能な場合は専門用語を避けます。開発者によく知られている用語は問題ありませんが、GitHub のしくみの詳細を読者が把握しているとは想定しないでください。
能動態を使用します。
簡潔にします。
- 簡単で簡潔な文を書きます。
- 複数の概念を含む複雑な文は避けます。
- 不要な詳細を削減します。

関連情報については、「スタイルガイド」の「ボイスとトーン」と「翻訳するコンテンツの記述」を参照してください。

ほとんどの読者は、記事全体を利用しません。そうではなく、ページを_拾い読み_して特定の情報を見つけるか、ページを_スキミング_して概念の一般的なアイデアを得ます。

コンテンツを拾い読みまたはスキミングする場合、読者はテキストの大きなかたまりをスキップします。自分のタスクに関連する要素や、見出し、アラート、リスト、テーブル、コードブロック、ビジュアル、各セクションの最初の数単語など、ページ上で目立つ要素を探します。

記事の目的と構造が明確に定義されたら、次の書式設定手法を適用して、拾い読みとスキミングのためにコンテンツを最適化できます。これらの手法は、すべての読者がコンテンツをより理解しやすくするのにも役立ちます。

太字やハイパーリンクなどのテキストの強調表示を使用して、最も重要な点に注意を向けます。テキストの強調表示は控えめに使用します。記事のテキスト全体の 10% を超えるテキストを強調表示しないでください。
書式設定要素を使用してコンテンツを分離し、ページ上にスペースを作成します。次に例を示します。
- 箇条書き (オプションで挿入小見出しを含む)
- 番号付きリスト
- 警告
- Tables
- ビジュアル
- コードブロックとコード注釈