目次

開発ドキュメントを書く前に決めるべき3つのこと【企画】

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

私はテクニカルライターとして開発ドキュメントを書いています。文章を書く上で「もっと読者の開発体験を高めるにはどうすればよいか」という問いに対して、自分なりの考えが固まってきたので、この記事でまとめてみます。

結論を先にいうと、文章を書く前に次の3つを決めます。

  1. その文章の読者は誰か
  2. 読者の悩みは何か
  3. 悩みを解決する方法

やること自体はすごくシンプルで、時間もそんなにかかりません。一方で、この3つを企画するかどうかで、文章のわかりやすさが大きく変わってきます。この記事を読むことで、文章を書く前に考えるべきことがわかり、もっとわかりやすい開発ドキュメントが書けるようになると思います。

著者
Hiroki Zenigami

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

テクニカルライティングを学ぶ

わかりやすい文章の書き方が学べる入門をnoteで公開しました。ブログやドキュメントなどを書くときにお役立てください。

なぜ企画が必要なのか

まず、この記事を書こうと思った背景から説明します。開発ドキュメントを書くときは、昔はいきなり文章を書きはじめていました。ただ実際には、「文章を書く前に考えること」というのがたくさんあります。

文章というのは、もちろん読む人がいるんですが、読む人には「その文章を読む目的」というのがあります。例えばエンジニアの方で、開発中にエラーが出てしまって、それをどう解決すればいいかわからない、という悩みがあったりします。

こういった悩みを解決するために、読者は文章を読みます。読者や悩みを決めないまま文章を書いてしまうと、結局何がいいたいのか、記事を通して何を伝えたいのかがわからない、というような問題が出る可能性があります。

こうならないためにも、読者とその悩み、加えて悩みをどう解決するか、ということを決めることが大切になってきます。

リーンスタートアップを元にしています

プロダクト開発の現場においても、まずはじめに顧客を決めて、顧客が抱える課題を見つけ、課題を解決する方法を決める、という「リーンスタートアップ」という手法があります。この記事の内容は、リーンスタートアップを開発ドキュメントに応用した手法となります。

開発ドキュメントを書く前に決めるべきこと

ここまでで書いた通り、文章を書く前に企画をすること、つまり読者とその悩み、そして解決策を決めることが大切です。この3つの項目の概要は、それぞれ次のようになります。

手順項目
1読者は誰かプログラミングを学びはじめたばかりの人
2読者の悩みは何かコードを実行しようとしたらエラーが表示された
3悩みを解決する方法エラーが出た原因と解決策を説明する

この3つの項目について、ひとつずつ見ていきます。

① 読者は誰か

読者というのは「その文章を誰が読むのか」ということになります。企画では3つの項目を決めますが、この読者を決めることが特に重要になってきます。文章というのは、もちろん読む人に向けて書きますが、例えば読む人が初学者と上級者では、伝わる言葉が大きく変わってきます。

例えばRubyにはJITというコンパイル方式があります。低レイヤーに詳しい方だと「JIT」という用語はふつうに使ってもいいと思いますが、プログラミングをはじめたばかりの初学者の方だと、そもそも「コンパイルとは何か」というところから説明しないといけないかもしれません。

このように、読者によって文章や構成がまったく変わってきます。わかりやすい文章を書くためには、はじめに読者をしっかり決める、ということが大切になってきます。

スポンサーリンク

② 読者の悩みは何か

読者を決めたら、次に読者の悩みを考えます。人は文章を読むとき、基本的には何かしらの悩みをもっています。例えば開発ドキュメントは、開発をしていてつまずいたりとか、つくりたいものがあるからつくり方を学びたい、といったときに読むと思います。

これは開発ドキュメントに限らず、例えばニュース記事を読むときも「暇をつぶしたい」という悩みがあるといえます。はじめに決めた読者の、どういう悩みについて書くのか。これによって、読者が文章を読んでくれるかどうかが決まります。

悩みを決める上でのポイントとして、ひとつのページで解決する悩みはシンプルにします。ひとつのページでたくさんの悩みを解決しようとすると、文章が長くなってしまい、わかりづらくなったり、結局何がいいたいのかがわからなくなったりしてしまいます。

③ 悩みを解決する方法

読者と、読者の悩みが決まったら、最後に解決策を決めます。これは「読者の悩みをどう解決するか」ということで、書く内容や文章の構成、伝え方などを決めていきます。

伝え方というのは、文章だけではなく、画像や表、箇条書きといった「読者にとってわかりやすい表現方法」についても考えます。実際に文章を書くときは、この解決策で決めたことをもとに書いていくことになるので、文章を書くときをイメージしながら解決策を決めるといいです。

おわりに

この記事では、文章を書くにあたって「あらかじめ決めておくべき3つのこと」を説明しました。つまり読者とその悩み、そしてその解決策を決める、ということです。

これを決めた上で、はじめて文章を書きはじめる、ということになります。これをすることによって、読者にとってわかりやすいことばで、悩みを解決してくれる開発ドキュメントになると考えています。

あわせて読みたい

著者
Hiroki Zenigami

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

スポンサーリンク

ブログをはじめよう

技術ブログの始め方を、たくさんの画像で分かりやすく解説しました。これまでブログをやったことがない人でも、エンジニアにとって重要なブログを今日から始められます。

ブログをはじめる