理論上最も分かりやすいQiita記事を書く方法

## はじめに
おはようございます、しなもんです。

**qiita記事、分かりやすく書けてますか？**

個人差はあるものの、できるだけ**分かりやすい記事を書く**ということは非常に重要なことだと思います。

しかし、**普段記事を書かない方**や、**伝えることが苦手な方**はそのコツが分からないのではないでしょうか？

https://help.qiita.com/ja/articles/qiita-community-guideline

> Qiitaはエンジニアにとって再利用性・汎用性の高い他のユーザーにとっても役にたつ、学びのある情報が多く集まっている場であり続けたいと考えています。

学びのある情報が多く集まっている場にするため、
自分以外の人が読んでも理解できる記事を書くためには、
自分の知識を分かりやすく記述することも大事だと思います。

正直、私も分かりやすい記事というのを意識して書けたことはありません。

そこでこの記事では、**理論上最も分かりやすい記事を書くコツ**をたくさん調べてみたので
実例を交えてまとめていこうと思います！

是非実践して、**沢山の情報を発信できるﾂﾖﾂﾖエンジニア**になってみましょう！

:::note info
一応、この記事のタイトルは「**理論上最も**」なので
ちゃんとそれぞれの根拠となる理論も提示していきます。
:::

## 目次

- 構成編
    - タイトルを工夫してみる
    - 目次を書いてみる
    - 主張やポイントを階層化する
    - 見出しを工夫して書く
    - 段落は効果的に使う
    - 導入部と結論を丁寧に書く
- 文章編
    - 簡潔で明瞭な文章
    - 専門用語の使用に注意
    - アクティブボイスを使用する
    - 例や比喩は最初に提示する
    - 読者との対話を意識する
- 視覚編
    - 行は適切に空ける
    - 視覚的要素を効果的に使用
    - テキストの強調を適切に行う
    - リストやテーブルを活用する
- おまけ

## 構成編

### タイトルを工夫してみる
Qiitaでは面白いタイトルの記事たくさんありますよね。

一番重要なのは、主要なキーワードや記事の本質を表すことです。
ですが、Qiitaにおいては読者の興味を引く工夫をすることが重要な気がします。

https://qiita.com/mu_tomoya/items/f78f1fad3a8b57ac7dc3

https://qiita.com/rubytail/items/6ad1e658d8f4093d831e

これらの記事、大好きです。

興味を引けるようなタイトルを考えるのが苦手な場合は、
疑問形、数字、対比、比喩などを使用することで少し工夫してみましょう。

:::note info
認知心理学の「カクテルパーティー効果」によると、人は関心のある情報に選択的に注意を向けるらしい。

効果的なタイトルは、**読者の関心**を引き、**記事の内容に注目させる**役割を持っているわけです。
:::

### 目次を書いてみる
目次を付けることで、読書は**情報処理を節約**し、**認知負荷を軽減**できます。

具体的には、目次から興味のあるセクションを選択することで、
**記事全体を読まなくても必要な情報を得る**ことができるようになります。

また、事前に文章の構成を理解することで、
読者に**集中させたまま読んでもらう**ことができます。
（目次が無い場合、文章が長く感じることで途中離脱の原因に）

ですが、全て書く必要はありません。
あくまで主要なセクションと重要な小見出しを含め、細かすぎる項目は避けるとよいです。
通常2〜3階層くらい。

Qiitaに通常備わっている目次は全部の見出しが出ちゃうんですよね。

:::note info
情報処理理論の「チャンキング」によると、情報を意味のある単位（チャンク）にグループ化することで、理解と記憶が促進されるそう。

目次は記事の内容を論理的なチャンクに分割し、
**読者の情報処理を助ける役割を果たす**ことができるんです。
:::

### 主張やポイントを階層化する

`#`や`*`等のマークダウンの記法を使って、階層化を意識してみます。
```
# 見出し1
## 見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6
```
```
* 箇条書き1
    段落1
    * 箇条書き2
        段落2
        * 箇条書き2-1
            段落2-1
```
Qiitaにおいて、`*`は`-`でも代用可能です。

先ほどの目次と似たような理由なのですが、こうすることで内部的にも視覚的にも情報の階層が分かれ、流れを理解しやすくなります。

:::note info
ゲシュタルト心理学の「プレグナンツの法則」によると、
人間の脳は構造化された情報を好む傾向があるそうです。

明確な構造は**理解と記憶を楽にする**、ということですね。
:::

### 見出しを工夫して書く
まずは、内容を正確に反映した見出しを付けることが大事です。
先述した通り、見出しは情報を分割し、事前に内容を理解しておく上で重要な役割を持っています。

ですが、時には読者の興味を引く魅力的な見出しもいいと思います。

https://qiita.com/CinnamonSea2073/items/d31e1b366da5b1d94126

工夫前「jQueryの利点」
↓
工夫前「それでもjQueryにしかない利点がある」

みたいな一工夫が個人的に気に行ってます。

:::note info
「プライミング効果」の理論によれば、先行する刺激（この場合は見出し）が後続の情報処理に影響を与えるそう。

工夫した見出しは**読者の期待を形成**し、**内容の理解を促進**する、ということです。
:::

### 段落は効果的に使う
一つの段落にたくさんのことを書いてはいけません。
必ず、一つの段落につき一つの話題を用意するようにしましょう。

その代わり、もし段落が長くなってしまったら積極的に分割しましょう。
逆に短すぎる段落は場合によっては関連する内容と統合したほうがいい場合もあります。

:::note info
認知負荷理論（Cognitive Load Theory）に基づくと、情報を小さなチャンクに分けることで、作業記憶への負荷を軽減し、理解と記憶を向上させることができるそうです。

**積極的に分割して情報を整理**しようってことですね。多分。
:::

### 導入部と結論を丁寧に書く
まず導入部で**記事の目的と概要を明確に示す**ようにしましょう。
`# はじめに`のように、導入部に段落を用意することを意識するようにすると良いです。

読者が期待できる内容や得られる知識を最初に示すことは、
読者に**記事を理解してもらう入口**になります。

また、結論では主要なポイントを再確認してみるのも大事だと思います。
内容に迷ったら、学んだ内容の要約と、
その知識をどのように活用できるかの具体的な提案をするといいようです。

:::note info
心理学の「初頭効果」と「新近効果」によると、人は情報の最初と最後をよく覚える傾向があるみたいです。
これらの部分を効果的に使用することで、記事の**主要ポイントの記憶を強化できる**らしい。
:::

## 文章編

### 簡潔で明瞭な文章
それぞれの単語が本当に必要なのか吟味し、
意味を明確に伝えるために、**本当に必要な言葉だけを使用**するようにしましょう。

特にこの業界では専門用語が非常に多いですよね。
この考え方はQiitaで記事を書く上で、とても大事だと思います。

また、複数の意味や文章を一つの文に詰め込まず、**必要に応じて文を分割することも大事**です。

:::note info
情報処理理論によると、人間の作業記憶容量は限られているみたい（ミラーの法則：7±2チャンク）。
簡潔な文章は**認知負荷を減らし、理解を促進する**らしい。
:::

### 専門用語の使用に注意
もし初心者も読むことが想定されている、他のジャンルのエンジニアも読むことが想定される記事では、
専門用語に**簡潔な定義や説明を記述**したり、**脚注を使用したりする**べきでしょう。

専門用語を一般的な言葉で言い換えたり、類似概念を用いて説明したりすることも、
分かりやすい記事を書くためには使えるテクニックです。

:::note info
ヴィゴツキーの「最近接発達領域」理論に基づくと、読者の現在の知識レベルからわずかに上の情報を提供することが学習に最適であるらしいです。

専門用語の適切な使用と説明はこの原則に沿ってます。多分。
:::

### アクティブボイスを使用する
文章に活力を与え、理解を促進するには、アクティブボイスというテクニックが効果的みたいです。

「～される」という受動態ではなく、「～する」という能動態を基本とし、
文章の主語と動作を明確にするということです。

:::note info
言語学の「主題と焦点」理論によると、アクティブボイスは文の主題を明確にし、
**読者の注意を重要な情報に向けやすくしてくれる**らしい。
:::

### 例や比喩は最初に提示する
最初に簡単な例や比喩を示すことで読者の理解の基準を設定すると、
それ以降の情報がその基準に沿って理解されやすくなります。

例として、初心者へ変数を説明する記事だとしましょう。

まず、アンカーとして変数は「**情報を保存する箱**」と説明します。
```
変数は、情報を保存する箱のようなものです。
```

その後、そのアンカーを含めて説明することで、分かりやすく書くことができます。
```
配列は、連続した箱の列です。
int[] arr = {1, 2, 3};は、arrという名前が付けられた連続した箱に
1, 2, 3という数値を順に入れることを意味します。
```

:::note info
心理学の「アンカリング効果」によると、人間は最初に提示された情報に強く影響を受け、その後の判断がその情報に引きずられるらしいです。
マーケティングで広く利用される効果であるらしい。
:::

### 読者との対話を意識する
記事中に質問を投げかけてみましょう。

レトリカルクエスチョンを使用して**読者の思考を促したり**、セクションの冒頭で**問いを投げかけ**その答えを本文で解説したりします。

ちなみに、レトリカルクエスチョンとは、質問の形っぽいけど遠回しに意図を伝える技法です。
（多用は逆に読みにくくなって良くないですが）

読者の疑問を予測して答えるのもいいと思います。
FAQセクションを設けたり、逆に本文中で「よくある質問」に対する回答を先回りして提供したりしてみましょう。

:::note info
社会構成主義の理論によると、学習は社会的相互作用を通じて促進されます。
対話的な文体は、読者の**能動的な参加を促し、理解を深める**ことができるらしい。

要するに、読者は見えないけど、コミュニケーションをとりながら記事を書くといいみたいな。
:::

## 視覚編

### 行は適切に空ける
余白は記事の15〜20%程度くらい確保し、視覚的な「息白」を作るようにしましょう。

効果的に空けることで、読みやすい記事を作ることができるわけです。

:::note info
人間工学の研究によると、適切な書式設定は読みやすさと快適さを向上させ、認知的疲労を軽減するそうです。
特に**長文を読む際に重要**とのこと。

Qiitaの記事では是非活用したい技法となるわけですね。
:::

### 視覚的要素を効果的に使用
関連性の高い画像や図表を入れていきましょう。
本文の内容を補完し、理解を深める画像や図表を配置してみるのです。

よくいらすとやさんのイラストを記事内で活用している記事もよく見かけますよね。
あれです。

:::note info
デュアルコーディング理論によると、情報が言語的および視覚的に同時に処理されると、理解と記憶が向上するらしい。
適切な視覚要素は文章の情報を補完し、読者に**記事を分かりやすく**感じさせてくれます。
:::

### テキストの強調を適切に行う
太字やイタリック体を使って重要なポイントを強調していきましょう。
キーワードや重要な概念に限定して使用し、読者の注意を誘導するのです。

ただし、使い過ぎは逆効果です。
強調箇所が多すぎると効果が薄れるため、1段落あたり1〜2箇所程度に抑えましょう。

:::note info
知覚の「ポップアウト効果」によると、視覚的に異なる要素は注意を引きやすいみたい。
ただし、過度の使用は「注意の飽和」を引き起こし、効果を減少させるそうです。
:::

### リストやテーブルを活用する
Qiitaのマークダウンでもちゃんと用意されてます。テーブル。

情報を整理し、一目で理解できるようにするのに役立ちます。

また、比較情報や多次元データをテーブル形式で整理することで、
情報の関係性を明確に示す効果もあります。

:::note info
情報アーキテクチャの原則によると、構造化された情報は認知的負荷を軽減し、情報の検索と理解を容易にするそうです。
リストやテーブルは情報の構造化にまさに効果的ですね。
:::

## おまけ

Qiita独自の手法？についても少し...

QiitaのようにCSSを使って文字サイズを表現できないプラットフォームにおいて、
見出しをこのように使うテクニックがあります。

https://qiita.com/Sicut_study/items/1723379221bd966b36aa

h3（`#`を3つ使う見出し）では仕切り線が発生しないことを生かし、
強調文字として使っている記事を見かけます。

これは正直誤りです。

https://developer.mozilla.org/ja/docs/Web/HTML/Element/Heading_Elements

ですがそこが難しいところで、
文字を適切に強調することは視覚的にはかなり重要なことであるわけです。

最終的には筆者のスタイルによるわけですが、
こういうテクニックもあると覚えておくと良いでしょう。

https://qiita.com/munieru_jp/items/fff0807f89c2896e701a

こんなのもあります。

## おわりに

最後に、この記事で紹介したことが実践できるように
記事を確認するチェックリストを作ってみました。

- 構成編
    - タイトル、工夫できてますか？
    （疑問形、数字、対比、比喩などを使用してる？）
    - 目次を書きましたか？
    - ちゃんと階層化しましたか？
    - 見出しを工夫しましたか？
    - 段落は一つにつき一つの話題を書いてますか？
    - 導入部と結論は丁寧に書いてますか？
- 文章編
    - 本当に必要な言葉だけを使用していますか？
    - 専門用語の使用に注意していますか？
    - アクティブボイスを使用しましたか？
    - 例や比喩は最初に提示しましたか？
    - 読者との対話を意識していますか？
- 視覚編
    - 行は適切に空けていますか？
    - 視覚的要素を効果的に使用しましたか？
    - テキストの強調を適切に行いましたか？
    - リストやテーブルを積極的に使いましたか？

正直時間がない際はここまで工夫して書くことはできないので、
必ず守れとは言えないのですが...
もし時間と意欲があれば、以上のようなことを意識して是非書いてみてください！