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

読みやすくするように記述する

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

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

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

拾い読み可能な形式

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

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

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

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