開発ドキュメントの文章における表現方法【箇条書き・表など】

本サイトはアフィリエイトプログラムを利用した広告を表示しています

私はテクニカルライターとして開発ドキュメントを書いています。文章を書いているのですが、文章だけだと分かりづらかったり、読みづらい文章になってしまいます。

分かりやすい文章を、それも早く書くには、箇条書きや表のような「表現方法」を押さえておくことがポイントだと考えています。この記事では、文章における表現方法についてまとめます。

Hiroki Zenigami

テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。

文章における表現方法とは

この記事でいう表現方法とは、文章をどう表現するか、その種類のことをいいます。例えば箇条書きや表などがあります。

世の中の開発ドキュメントにはどんな表現方法が使われているかは、実際の開発ドキュメントを見てみるのが早いです。これについては「開発ドキュメントを書くときの参考になるサイト」をご覧ください。

この記事では、上記参考サイトの中でも使われている表現方法をもとに整理しています。

よい文章を、早く書くには、書くための道具を準備しておくことが大切だと考えています。文章の表現方法は、料理における菜箸やおたまのようなものだと思います。つまり、品質の高いものを、早く作るための道具になります。

文章においては、どんな表現方法があるのかを押さえておくことが大切です。

まず、基本となる表現方法を5つ説明します。これらはどんな開発ドキュメントでも使いやすく、分かりやすさが大きく向上します。

それぞれについて簡単に説明します。

箇条書きや、情報の要点を簡潔に伝える手法です。順序があるものと、ないものがあります。文章を書いていて要点がつかめなかったり、文章が長くなってしまったときは、箇条書きにすると伝わりやすくなったりします。

表は、情報をいくつかの項目を元に整理して伝える手法です。ある項目について、いくつかのものを比較するときなどに、文章よりも伝わりやすくなることがあります。

技術的な内容によっては、文章で説明するよりも、実例を見た方が早いことがあります。実装例やコマンドの実行例などを提示することで、文章と合わせて読者に理解を促すことができます。

説明したいことを、図を用いて視覚的に伝える手法です。図があることで、文章と合わせて理解を促すことができます。特に理解が難しい内容を説明する場合に、図による説明が有効になります。

例えば、処理の流れはシーケンス図を用いたりします。シーケンス図については「PlantUML入門①: シーケンス図の書き方」をご覧ください。

補足情報や注意事項などを、文章とは別の見た目で視覚的に強調して伝えます。特に気をつけてほしいことを伝えるときなどに効果的な手法です。

いろんな表現方法を織り交ぜる

文章が続くと、理解が難しいだけでなく、視覚的にも締まりがなくなってしまいます。箇条書きや表など、上記の表現方法を適切に織り交ぜることで、分かりやすく、視覚的にも読みやすい開発ドキュメントにつながります。

ここまでで説明した5つが基本的な表現方法になります。もちろん、他にもいろんな表現方法があります。

次に説明する方法は、効果的ではありますが、サイト側の実装コストや、コンテンツの制作コストが大きくかかってきます。コストをかけてでも分かりやすく伝えたい場合に検討するとよさそうです。

こちらもそれぞれについて簡単に説明します。