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)
講演内容をスライドで復習したい人向け。