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

私はテクニカルライターとして開発ドキュメントを書いています。

文章を書いているのですが、文章だけだと分かりづらかったり、読みづらい文章になってしまいます。

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

この記事では、文章における表現方法についてまとめます。

著者
Hiroki Zenigami

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

目次

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

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

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

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

なぜ表現方法を知っておく必要があるのか

よい文章を、早く書くには、書くための道具を準備しておくことが大切だと考えています。

文章の表現方法は、料理における菜箸やおたまのようなものだと思います。つまり、品質の高いものを、早く作るための道具になります。

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

基本的な表現方法

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

番号表現方法概要
1箇条書き順序のある、またはない情報の要点を簡潔に伝える
2いくつかの項目を元に情報を整理する
3ソースコード実際の実装例やコマンドを提示する
4概念図やシーケンス図を用いて、視覚的に情報を伝える
5メッセージ補足や注意事項などを視覚的に強調して伝える

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

1. 箇条書き

箇条書きや、情報の要点を簡潔に伝える手法です。順序があるものと、ないものがあります。

文章を書いていて要点がつかめなかったり、文章が長くなってしまったときは、箇条書きにすると伝わりやすくなったりします。

2. 表

表は、情報をいくつかの項目を元に整理して伝える手法です。

ある項目について、いくつかのものを比較するときなどに、文章よりも伝わりやすくなることがあります。

3. ソースコード

技術的な内容によっては、文章で説明するよりも、実例を見た方が早いことがあります。

実装例やコマンドの実行例などを提示することで、文章と合わせて読者に理解を促すことができます。

4. 図

説明したいことを、図を用いて視覚的に伝える手法です。図があることで、文章と合わせて理解を促すことができます。

特に理解が難しい内容を説明する場合に、図による説明が有効になります。

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

5. メッセージ

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

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

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

その他の表現方法

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

次に説明する方法は、効果的ではありますが、サイト側の実装コストや、コンテンツの制作コストが大きくかかってきます。

コストをかけてでも分かりやすく伝えたい場合に検討するとよさそうです。

番号表現方法概要
6用語集読者によって分かりづらい用語を説明する
7動画情報を動画で説明する
8プレイグラウンドウェブ上で動作を確認できる機能を提供する

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

6. 用語集

読者にとって分かりづらい用語を、ツールチップなどで補足します。

開発ドキュメントにいろんな読者がいる場合、習熟度が低い人に合わせて説明しようとすると、文章が冗長になることがあります。かといって、説明しないと理解しづらくなります。

この場合、用語集があることで、必要な人にだけ補足することができます。

7. 動画

動画はその名の通り、文章だけで伝わりづらいことを動画で説明します。例えば、ContentfulTerraformは動画によるチュートリアルを提供しています。

特にチュートリアルのような、読者にとって入り口となるテーマで効果的です。

動画は制作コストがかかるのはもちろん、内容が変わったときに修正しづらいという欠点もありますが、ポイントを絞って提供するとよさそうです。

8. プレイグラウンド

プレイグラウンドは、ライブラリやAPIなどの動作をウェブ上で試す機能になります。例えばStripeはPayment Elementという機能のプレイグラウンドを提供しています。

機能を実際に体験できるので、もっとも伝わりやすい表現方法といえます。開発コストがかかりますが、これも可能であればポイントを絞って提供したいです。

おわりに

開発ドキュメントは、文章だけだとどうしても伝わりづらいです。箇条書きや表といった表現方法をうまく活用することで、分かりやすい文章を、早く書くことができます。

基本的な表現方法だけでも、しっかり押さえておきたいところです。

著者
Hiroki Zenigami

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

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