技術的な文章を書くための1歩、2歩、3歩

ちょっと書きたくなったので書くんじゃーい！
この文章を読み終わった時、読者がそれなりわかめ品質な文章を出力できるようになり、どこかに寄稿した時に全面リテイクを食らったりしないようになることを目指します。

mhidaka が 0歩目を書いてくれました！

背景

筆者は普通のエンジニアです。その辺の開発とかしてる会社に勤めています。技術系の原稿も書きます。
原稿書きでご飯食べてるわけではありません(晩ご飯が豪華になることは稀にあります)。

今まで有能なレビューワー(muなんとかさんとか)編集さんとか(某社の安藤さんとか)とかとかに鍛えていただきました。
この場を借りてお礼を述べておきたいと思います。ありがとうございます。

なお、この文章は2013年10月時点での筆者(わかめ)のやり方です。
将来的にはより良いやり方を見つけるでしょうし、これとは全く違う書き方で上手にやっている人もいると思います。

これから偉そうな事述べるであろう筆者の書いた記事とかスライドとか。
あ、僕の今までのQiitaの記事のストック数見ます？(ﾄﾞﾔｯ

準備体操 なぜ文章を書くのか

いきなりですが、質問です。貴方は何故原稿を書こうとしているのでしょうか？考えてみましょう。

• 自分の知識・経験に広める価値があると判断している
  • 言い換えると、何かを布教したい
• 最新の情報について勉強したい
  • 言い換えると、ついでに原稿料貰いたい

だいたいこんな所だと思います。

知らない事も書いてみよう

多くの人が勘違いしがちなのですが、自分が知らない事について書くというのは、実は罪ではありません。貴方は許されています。知らない事について調べて書いてもよいのです。
文章を書くということは、その内容について責任を持つということと不可分です。つまり、貴方は日本語を話す人としては、一時的にであれその分野について最も詳しく知っている人になる必要があります。

その分野について最も詳しく、というと死ぬほど難易度が高そうに思いますが、実のところそんなに難しいことではないのです。
例えば、モンスターハンター4を極めし者 になるのは死ぬほど難しいと思います。ですが、モンスターハンター4の下位地底火山で最短ルートで大地の結晶を集めて帰還することを極めし者 くらいまで限定すると、不可能ではないように思われます。
まずはそこを筆者自身の技術的到達点として狙って行きましょう。

もし万が一、責任を持ちたくない場合は、見るからにちゃらんぽらんで、信頼がおけないような文章に仕上がるように努力しましょう。

第1歩 設計

まず、最初にこれから作成する文章の設計を行います。
設計するのは以下の要素についてです。

• 対象読者を考える
  • 言い換えると、原稿を読む前の読者のレベルを設定する
• 読み終わった時に読者が得られるものを考える
  • 言い換えると、原稿を読み終わった後の読者の到達点を設定する
• 文章の構造について考える
  • 章・節・項 を考えます。
    • Markdownでいうと、# と ## と ### を先に書く
    • 文章の長さに応じて考える深さを変えます。この文章は深さ1で設計しました。
• サンプルを作成する場合、どういうサンプルを作成するか検討する
  • 実はこれがかなり難しいです
  • 説明したい要素が十分に含まれている
  • 説明しない要素かつ難しいものがなるべく含まれないようにする
  • 短いソースコードにできる
  • 説明する技術のメリット(とデメリット)が明確にわかる

筆者(わかめ)の場合、この工程に意識的に取り組む時間はおおよそ10分〜2時間くらい消費されます。
かける時間は短いですが、ここを真面目にやらないと後から大炎上するのは皆様も知る通りです。

文章構造を考えるうえで

文章構造について考える。について少し詳しく書いておきます。
筆者が留意しているのは、読者は有限オートマトン(有限状態機械)だということです。
初期状態(対象読者を考える)と受理状態(読み終わった後に読者が得られるものを考える)は既に考えてあるはずです。
ここでいう章・節・項を設計することは、読者の状態を初期状態から受理状態に変化させるための途中の状態を設計することに他なりません。
読者を無理なく初期状態から受理状態に遷移させるために、情報を与える順序は前後してはいけませんし、途中に歯抜けが発生してもいけません。
そこを正しく行うにはどういう状態で情報を渡していけばよいのかを考え、設計を行います。

筆者は、筆者内部での課題の設定(と読者への共有)、筆者の考えた解決方法の開陳(と読者への共有)、筆者の考えた解決方法の提示と結論 を示すと良いと考えています。

また、その他の重要な点として、サンプルコードを用意する場合について。
ソースコードを解説する順番に説明の順番がかなり依存するので、サンプルを用意する場合は文章構造がサンプルコードの説明をしやすい順番にできるかも考慮に入れます。

それからそれから？

さて、上記4要素を書ききるためには、まずは書く対象について概要を知らなければなりません。
ドキュメントやサンプルコードがあれば、それに目を通して概要を掴んでおくと良いでしょう。

ここまで書き終わったら、完成までにどういう事を調べなければいけないか、どういう障害がありうるか、ある程度あたりがつくようになっているでしょう。
この時点で、何か憂いがある場合は解決しておきます。他の人とのネタ被り・自社の機密に抵触するか・機材や経費は許容範囲内か、などなどが考えられます。
懸念事項は全てクリアしておき、もし編集さんなどの第三者がいる場合はこの時点で一旦相談しておくと良いでしょう。
この辺りの手を抜いてしまうと、後々例外やエラーの処理方法を最初に設計しておかなかったシステムの如く、後から仕組みを追加してテストを追加して工数は倍々ドン！みたいな身に覚えのある辛い展開になってしまいます。

ネタが被るのは悲しいことですね

ネタ被りについても少し言及しておきます。
他の人が書いた原稿について、ネタが大なり小なり被ることはある程度仕方がない部分があります。
パクリは論外ですが、ネタが被るのは仕方がないと割りきってしまいましょう。

もし、徹底的にネタ被りを避けようとするとどうなるでしょうか？
英語の公式ドキュメントがあるのにそれを日本語に翻訳することは言語は違いますが内容的には完全にネタ被りなので、行わないほうがいいでしょう(実際は母国語で公式ドキュメントが読めることは多くの人にとって価値があります)。
C言語についての本はたったの1冊(K&Rですかね)あれば十分で、2冊目以降はネタ被りになるので不要になります(実際は2013年にもなって未だに新しいC言語の本が出版されています)。
ですが、実際には括弧内に書いた通り、ネタ被りと判定しようと思えば出来る文章でもどんどん作成されていますし、広く受け入れられています。
つまり、あなたが付け加えられるオリジナルな価値・説明があればそれで良いのです。

もし、ネタの被り先が知合いであれば、一言断ってみると、精神衛生上大変良くなるので、聞いてみると良いでしょう。

第2歩 調査

設計が終わったら、技術的な調査に入ります。
実際のシステム開発だと、技術的な調査を行ってから設計に入ると思います。ですが、原稿の場合は本格的な調査は設計の後になります。

調査フェーズで行わなければいけないのは以下のとおりです。

• サンプルコードの完成
  • サンプルコードの出来によって、原稿の設計を変える必要が生じるかもしれません。完成させていきましょう。
• 技術的不明点の解消
  • サンプルコードを作るにつれ、不明点が発生してくるはずなので可能な限り調査する
  • Androidとかだとオープンソースなのでどこまでも追っていけるので楽ですね
  • 調査終了の基準点として こうすれば何かが達成できる、筆者が知らない機能や仕様は多分ない、これはどうあがいても実現できない事がわかる あたりでしょう。

筆者(わかめ)の場合、この工程に意識的に取り組む時間はおおよそ2日〜3日(1日6〜8時間換算)くらい消費されます。

第3歩 実装

さて、実際に原稿をもりもり書いていきましょう。
設計段階で枝(章・節・項)は定義しているはずなので、そこにもさもさと葉を生やしていくだけの簡単な作業です。
既にサンプルコードも出来ており、判明している技術的に不明な点は消化されているはずです。
そのため、ここからは日本語と戦う作業になります。

文章を書く時に筆者が意識的に行っている事がありますので述べていきます。

• 日本語が一意に解釈できるか。誤解を生まないか。
• 対象読者に未知の用語を使って説明していないか
  • 説明の順番を変更する必要があれば思い切って変更する。そうならないように設計時によく検討していくことも重要。
• 筆者の中で常識だと思っている事が本当に常識かどうかを検討する。社内で常識になっているものは誤判断しやすいので留意する。
  • 常識じゃないものを常識だと判断すると、説明をすっ飛ばすというミスに派生する
• 要求・結論を先に述べているか。犯人はヤスは正義。オリエント急行殺人事件の犯人は☓☓☓。
  • これから説明する内容をざっくり最初に説明するのは大事
  • そこをサボると、読者の中に無数の解釈の枝(主旨の推測)が発生してしまい、書いてある内容がするりと入っていかなくなってしまいます。読者の計算量を減らすために積極的に枝刈りを行いましょう。
• 言い換えを考えてみて、元の言い方と言い換えの方のどちらが意図が伝わりやすいかを検討し、必要があれば書き換える。
• 断定口調で書けているか。だと思う、とかであろう、とかは だ、である、に変更する。不安がある場合は追加の技術的調査を行う。
• 用語が統一され、正しく用いられているか。
  • 例えば、1つの文章中に if文 と if式 という書き方が混ざっていてはいけません。それぞれ、指すものが違います。用語が正確に用いられているのかというのは、文章全体の信頼性に関わります。
    • 例えば、完全に正しくて有用な技術的文章でも、Javaの事をJavaScriptと書いて説明していたら、信頼度は地に落ち、他の部分も間違っている可能性のある、取るに足らない文章と判断されるでしょう。
• 文章を分割できないか検討する。
  • 長い1文よりも、短い2文です。句点で切っても正しく意味が伝わる場合は積極的に切ります。
• 文の先頭に何かをつけるのを我慢する。
  • または、しかし、さらに、なので、 などは文の先頭に付けたくなってしまう魔力を持っています。そうしたほうが読みやすい文に見えてしまう気がするのです。それは気のせいなのでなるべく省けるように努力します。
• 句読点は適切に打たれているか。
  • わかめさんめっちゃ読点多いマンです。

また、気がついたら随時リファクタリングを行います。
節の位置の交換とかも随時行いますが、なるべく最初の設計から変更しないで済むように留意します。

筆者(わかめ)の場合、この工程に意識的に取り組む時間はおおよそ1日(1日6〜8時間換算)くらい消費されます。
レビュワーに頼んだ後の指摘事項修正や校正などに費やす時間はここに含みません。

まとめ

さて、いかがでしたでしょうか？
みなさんもぶりばり技術文章を書いて、読んでくれた人をどんどん洗脳して自分のシンパにしましょう。
さぁ！みんなもTypeScriptをやろう！(ｵｰ

僕も、こういう事を言語化して考え、なるべく体系的に把握するよう務めるようになったのも、ここ2年くらいの事です。
この文章を書いて、あだむろっかとかに『2.3本書いてた奴があんな事言ってるｗｗｗｗm9(^Д^)ﾌﾟｷﾞｬｰ』と煽られました。
2.3本はたぶん僕が多くの人に読ませるために書いた初めての技術的文章で、あだむろっかとかますいさんにﾎﾞｯｺﾎﾞｺにされた事を懐かしく思い出します。今はあの時よりはマトモになってると思うんですけどね。
簡潔に言うと、最初はクソみたいな文章を出力してしまうものだし、使い古されている言葉ではありますが継続は力なり、ということです。まずは恐れず、クソを生産して周囲の識者にボコボコにしてもらえたら最初の洗礼を受けられた、と捉え一安心すると良いと思います。

なお、この文章を書くにあたり、編集履歴に作業風景がなるべく残るようにしてみました。
興味があればご覧ください。
これだけの文章を書くのに約3時間かかっているようですね。短いのか長いのかもわかりませんが。