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

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

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

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

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

Hiroki Zenigami

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

なぜ企画が必要なのか

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

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

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

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

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

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

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

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

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

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

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

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

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

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