📄
[ドキュメント] わかりやすい文章を書くには
はじめに
この記事では、仕様書等の文章をわかりやすく記載するコツをまとめております。
参考資料
結論
1. 必要な情報を正しく得られる
- 曖昧さを廃し、明確な文章を書く
- できるだけ具体的に書く
サンプル文章
# 数字で表現する
- 画面の表示が早い
+ 画面が2秒以内に表示される
サンプル文章
# 万人にわかりやすい例文を提示する
- iPhoneは簡単に使用できる
+ iPhoneは、アプリケーションのデザインと操作に一貫性があり、
+ ユーザーが異なるアプリケーションを共通の操作感覚で使える
2. 効率良く理解できる
ほとんどの読者は最後までドキュメントを読まないため「要点を先に伝える」
1. 重要なことから書く
- 言いたいこと
- その理由や説明
2. 読み手の視点で書く
読み手にとって何をしたら何をしてくれるのかを明記する
※開発者目線で書かない
サンプル文章
# 開発者の視点
- アプリの自動アップデートが有効になっていると、
- 定期的にアップデートの有無を確認し、自動的にアプリをアップデートします。
# ユーザーの視点
+ アプリの自動アップデートが有効にすると、常に最新版のアプリを使用できます。
3. 能動態と受動態を使い分ける
サンプル文章
# 文章全体が能動態のままで読みにくい
- アプリの自動アップデートが有効にすると、自動的にアプリをアップデートします。
# 文章の後半が受動態に変わって読みやすい
+ アプリの自動アップデートが有効にすると、自動的にアプリをアップデートされます。
4. 一文一義
サンプル文章
- iPhoneはアップル社が開発し販売するスマートフォンで、シンプルで洗礼.........
+ iPhoneはアップル社が開発し販売するスマートフォンです。
サンプル文章
- ホーム画面で[設定]を選択し、[Wi-Fi]を選択し.........
+ 1. ホーム画面で[設定]を選択します。
+ 2. [Wi-Fi]を選択します
+ 3. ......
3. 不快さがなく、ポジティブに受け止められる
- 肯定形で書く
- 信頼される表現で書く
サンプル文章
- 100件を超えるデータは登録できません。
+ 100件までデータを登録できます。
禁止事項はあえて否定形で書く
サンプル文章
- 電源を入れたままにしてください
+ 電源を切らないでください
Discussion