1. はじめに

Markdownって、簡単に書けるし、どこでも使えて便利。
見出し、箇条書き、リンクなど、基本だけでもそれっぽい文章になる。

でも、「読みづらいな」と思う文章、ありませんか？

・改行がなくて詰まってる
・見出しがバラバラ
・言い回しに統一感がない

どれも、Markdownを使ってるとよくある失敗です。

この記事では、
Markdownだけで、伝わる文章を書くコツを紹介します。

見た目は地味でも、ちゃんと伝わる。
そんなドキュメントを書くためのヒントになればうれしいです。

2. Markdownで伝わらない文章の特徴

構成がバラバラ

見出しの順番がぐちゃぐちゃ。
読む人は「どこまでがセットなの？」と迷ってしまいます。

❌ ダメな構成

## 概要
このツールは便利です。さまざまな機能があります。導入方法も簡単です。

## 注意点
- Macでは一部機能が動作しない場合があります。
- ネットワーク接続が必要です。

## 使い方
- ファイルをダウンロードします。
- 起動します。

## 特徴
- 軽量です。
- シンプルなUIです。

✅ 良い構成

## 概要
このツールは、軽量でシンプルなUIを備えた便利なアプリケーションです。

## 特徴
- 起動が早く、動作も軽快  
- 初心者にも使いやすいUI設計  
- 導入が簡単

## 使い方
1. ファイルをダウンロードします。
2. アプリを起動します。

## 注意点
- Macでは一部機能が制限されることがあります。
- 利用にはネットワーク接続が必要です。

改行がない・詰まりすぎている

1文が長くて、段落も詰めすぎ。
画面いっぱいに文字が詰まっていると、読む気がなくなります。

文体がバラバラ

「です・ます」と「だ・である」が混ざっていたり、急に語り口が変わったり。
統一感がないと、読みにくさにつながります。

箇条書きが多すぎる

なんでもかんでも箇条書きにすると、結局なにが重要かわからなくなります。

3. Markdownで伝わる文章にするには

見出しで構造を見せる

見出しは「構成」の柱。
レベル（#）を揃えて、読み手の頭を整理してあげましょう。

# アプリの使い方

## 1. アプリの概要
このアプリは、タスク管理を効率化するためのシンプルなツールです。

## 2. インストール手順

### 2-1. 前提条件
- Node.jsがインストールされていること
- インターネット接続があること

### 2-2. セットアップ手順
1. リポジトリをクローン
2. `npm install` を実行
3. `npm run start` で起動

## 3. 主な機能
- タスクの追加・編集・削除
- タスクのドラッグ＆ドロップで並び替え
- ステータスごとのカラム表示

## 4. 注意点
- データはローカルストレージに保存されます
- スマートフォンでは一部UIが崩れる可能性があります

このように、#〜###の見出しを階層的に使うことで、文書の全体構造が一目でわかるようになります。

一文一情報。改行はこまめに

1文に詰め込まない。
伝えたいことは小分けにして、適度に改行。

読みやすさは、余白から生まれます。

文体を決める。揃える

最初に「です・ます」でいくか、「である調」にするか決めておく。
揃っているだけで、読みやすさは変わります。

コードや表には一言添える

コードや表は、補足説明がないと“謎のブロック”になりがち。

「何をするコードか」「何を比較してる表か」
簡単でもいいので一言つけましょう。

4. おわりに

Markdownだけでも、伝わる文章は書けます。

大事なのは、整える力。
構成、改行、文体、言葉の選び方。

読み手のために、一つひとつ丁寧に。

書き方に迷ったら、「読み返して、読みにくいところを直す」だけでも効果があります。

技術より前に、気配りから。
それが伝わる文章を書く第一歩です。

参考リンク

Readable Markdown ～読みやすい Markdown の書き方～
→ https://qiita.com/sta/items/768bd88e9d7badc98260
【和訳】エンジニアのためのテクニカルライティング by Google
→ https://zenn.dev/kibe/books/3355e3a0775e58/viewer/f5c52d
サイボウズテクニカルライティング開発研修2023（YouTube講演）
→ https://www.youtube.com/watch?v=vHEzSQ3YFXk)
講演スライド資料（Speaker Deck）
→ https://speakerdeck.com/naohiro_nakata/technicalwriting)
講演内容をスライドで復習したい人向け。