ドキュメント

テクニカルライティングとは

読者や目的に合わせて技術をわかりやすく伝える手法

利点

書き手、読み手双方にある

対象

実用文

• 議事録
• 報告書
• 技術書
• 仕様書
• マニュアル、FAQ

整理の鉄則

• 概要から具体
• 全体から部分

例

• まず、全体像を伝える
  • 魅力も加えると良い
• 次に、構成要素を説明する
• その後に、構成要素同士の関係を語る
• 必要なら、競合と比較する

重要なことから書く

• Bad
  • システムを正常に起動できなくおそれがあるので、アップデート中は電源を切らないでください
• Good
  • アップデート中は電源を切らないでください。システムが正常に起動できなくなります。
• 英語の順番だね

一文一義で書く

• Bad
  • ～は、～で、～があって、～が特徴です。
• Good
  • ～はです。～を備えています。～が特徴です。

簡潔に書く

• これは場合による。
• 「また」「したがって」などはいらない場合が多い。

受動態、能動態を使い分ける

• Bad
  • 「削除」をクリックすると、全てのデータを削除します。
• Good
  • 「削除」をクリックすると、全てのデータが削除されます。
• ユーザーからみた能動と受動で表現するとわかりやすい。
  • ユーザーの操作
    • 能動
  • システムの動作
    • 受動

具体的に書く

• Bad
  • メール通知の設定を確認してください
  • 間隔を少し空ける必要があります
• Good
  • メール通知が有効になっていることを確認してください
  • 3~5分の間隔が必要です

肯定形で書く

• Bad
  • ５名以上の予約は受け付けられません
• Good
  • ４名まで予約できます。
• 簡潔に理解できる
• ポジティブな印象になる。

二重否定を使わない

• Bad
  • ファイルA以外は削除しないでください
• Good
  • ファイルAだけを削除してください

係り受けを明確にする

• Bad
  • 消毒液Aのように刺激の強くない消毒液を使ってください
    • 消毒液AはOK？NG？
• Good
  • 消毒液Aのように、刺激の弱い消毒液を使ってください。
  • 消毒液Bのような刺激の強い消毒液は使ってはいけません。

主語や目的語と、術後を近づける

• Before
  • データは、自動同期を無効にした場合は手動で同期しない限りバックアップされません。
• After
  • 自動同期を無効にした場合、手動で同期しない限りデータはバックアップされません

列挙には箇条書きを使う

• Before
  • 名前、住所、メールアドレス、電話番号、及び誕生日の入力は任意です
• Good
  • 次の項目の入力は任意です
    • 名前
    • 住所
    • メールアドレス
    • 電話番号
    • 誕生日

参考

• https://speakerdeck.com/naohiro_nakata/technicalwriting