開発ドキュメントの書き方。意識したい9つのこと【技術編】

私はテクニカルライターとして、開発ドキュメントを書いています。読みやすい、分かりやすい文章を書くときは、

  • 一文を短く切る
  • 結論を先に述べる

など、必ず意識することがあります。

以前は満足のいく文章を書けませんでしたが、文章を書く中で学び、「これを意識すればよい文章が書ける」という自分なりのルールを見つけました。

このような内容はいろんなところで言われているので、特に真新しい内容はないかもしれませんが、よりよい文章を書くきっかけになればうれしいです。

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。

目次

文章を書く前にやること

よい文章を書くには、実際に文章を書く前に、読者は誰か、どういう悩みを解決するのかを企画することが大切です。また、それを元にアウトラインを書いておきます。

このふたつを元に文章を書くことで、読みやすい開発ドキュメントにつながります。これについては、次の記事をご覧ください。

開発ドキュメントの書き方

企画とアウトラインの作成が終わったら、実際に文章を書いていきます。

文章を書くときは、次の9つを意識して書きます。これだけで、読みやすさ、分かりやすさが大きく向上します。

  1. 一文を短く切る
  2. 結論を先に述べる
  3. 指示語を使わない
  4. 主語を明確にする、述語との距離を近づける
  5. ひらく・閉じるを統一する
  6. 再現条件を示す
  7. 前提を揃える
  8. 見出しや箇条書き、表などを適切に用いる
  9. 読者に伝わる用語を使う

ひとつずつ説明します。

1. 一文を短く切る

一文とは、句点で区切られた文字列のことをいいます。この一文を短く切ります。

一文が長いと、文章を読んでいるときに、頭の中に情報が積み重なっていきます。結果として、文章の理解が追いつかなくなります。

どうすればよいかというと、例えば「〜で」や「〜が」のようなつなぎ言葉が出てきたときに、そこで区切ります。

こうすることで、一文が短くなり、読みやすい文章につながります。

2. 結論を先に述べる

文章を書くときは、まず結論を先に書きます。はじめに結論がないと、「結局何がいいたいんだろう」と、読む人がモヤモヤしてしまいます。

背景や例などを書いてしまいがちですが、まずは結論を先に書くことを意識します。

3. 指示語を使わない

指示語とは「それ」や「これ」のようなものですが、できる限りこの指示語を使わないようにします。

文章の中で指示語が出てくると、「それって何だっけ?」となり、前の文章に戻ってしまいます。「それ」が分かったとしても、今度は「どこまで読んだっけ?」という問題も生まれます。

指示語を使わなければ、文章を読む上で前に戻ったりする必要がありません。

「指示語を一切使わない」というのは難しいかもしれませんが、適切に用いることで、読みやすい、分かりやすい文章につながります。

4. 主語を明確にする、述語との距離を近づける

文章を書いていると、つい主語を省略してしまうことがあります。例えば、

分かりやすい開発ドキュメントを書くことを目的とした講義を先日受講した

という文章があったとします。この主語は「私」かもしれませんし、別の誰かかもしれません。

また、この文章における述語は「受講した」になりますが、主語との距離が離れているため、「受講した」のは誰かが分かりづらいです。

これを防ぐには、次のような文章にします。

私は先日ある講義を受講しました。この講義は分かりやすい開発ドキュメントを書くことを目的としたものでした

文章は長くなりましたが、主語が明確で、述語との距離も近いため、読みやすく感じると思います。

主語を明確にし、述語との距離を近づけることで、読者の誤解を減らすことができます。開発ドキュメントでは特に気をつけたい項目です。

5. ひらく・閉じるを統一する

「ひらく」とはひらがなで書くことで、「閉じる」とは漢字で書くことをいいます。例えば、

ひらく閉じる
はじめに初めに
とき
たとえば例えば
ください下さい
すべて全て

のようになります。このひらく・閉じるに決まったルールはありませんが、同じ言葉に関しては、開発ドキュメントで統一します。

具体的には、同じ開発ドキュメント内では、同じ意味で「はじめに」と「初めに」を混用しない、ということになります。

ちなみに、漢字が多いと固く、ひらがなが多いとやわらかい印象を読者に与えます。ひらがなが多すぎると、稚拙な印象を与えてしまいます。

参考までに、日経クロステックの記事では、「漢字3割、ひらがな7割」が読みやすいとしています。

ひらく・閉じるのルール

テクニカルライティングの現場では、「記者ハンドブック 第14版: 新聞用字用語集」をひらく・閉じるの根拠にしているところが多いようです。

6. 再現条件を示す

再現条件とは、ライブラリやフレームワークのバージョン情報などをいいます。この再現条件を記事の中で示す必要があります。

バージョンが変わると、ソフトウェアの動作が変わる可能性があります。どの動作環境で検証したのか、記事の内容においては正しく動作するようにしておくことが重要です。

7. 前提を揃える

読む人のバックグラウンドによって、文章の読み取り方が変わる可能性があります。

例えば「テクニカルライティング」という用語について、ウェブの文脈であれば開発ドキュメントが連想されますが、家電製品の場合は取扱説明書になります。

その記事が前提としている用語について、読み手によらず認識を揃えるために、前提を揃えることが読みやすさにつながります。

8. 見出しや箇条書き、表などを適切に用いる

文章だけだと読みづらい、分かりづらい場合があります。このようなときは、見出しや箇条書きなど、文章以外の表現方法で情報を伝えます。

箇条書きのような表現方法について詳しくは、「開発ドキュメントの文章における表現方法【箇条書き・表など】」をご覧ください。

9. 読者に伝わる用語を使う

開発ドキュメントはいろんな人が読むと思います。その製品に詳しい人もいれば、初学者もいるでしょう。

読む人によって、伝わる用語は変わってきます。つまり、読み手に合わせて使う用語を選ぶ必要が出てきます。

「文章を書く前にやること」でも書きましたが、文章を書く前に読者を決め、この読者に合わせて文章を書くことを意識します。

書き方を身につけるには

以上の9つを意識して文章を書くことで、読みやすい、分かりやすい文章につながります。では、この技術をどうやって身につければよいのでしょうか。

もちろん業務で開発ドキュメントを書く際に意識することで、少しずつ身についていくと思います。

開発ドキュメントを書く頻度が高くない場合は、ブログや個人出版、あるいはTwitterなどで実践するとよいと思います。

私は技術ブログを書いているということもあり、ブログがもっともよい方法だと考えています。私はテクニカルライターになるための文章力を、ブログを通して身につけました。

技術ブログについて詳しくは、「技術ブログ入門」をご覧ください。

おわりに

読みやすい、分かりやすい開発ドキュメントを書くための9つのことを説明しました。文章を書くときは、この技術を意識することで、よりよい文章につながります。

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。

\ よかったらフォローしてください /
関連記事関連書籍
人気記事
applis
アプリケーション開発について学ぶブログ
お問い合わせ
ご意見・ご質問やお仕事のご依頼などは以下よりお願いいたします
お問い合わせ
© 2020-2022 applis