技術記事の3類型: 初心者による技術記事執筆のすすめ

今日は初心者が技術記事を書くことについての議論を見かけました。

一言に技術記事と言っても、初心者が書く記事と上級者が書く記事、あるいは初心者向けの記事と上級者向けの記事は、内容のレベルだけでなく書かれる目的・提供価値も異なるものです。そのため、筆者の考えでは技術記事を適切に分類しなければ議論は成り立ちません。しかし、筆者の見える範囲では技術記事を分類して考えようという考え方はあまり見かけられませんでした。

そこで、この記事では技術記事に対する3類型の分類を提案し、それを基に技術記事の執筆について考察します。

ご注意: この分類やこの記事の内容全般は筆者の私見であり、唯一の正解であると主張するものではありません。

技術記事の3類型

筆者の考えでは、技術記事は比喩的に「学習ノート」・「教科書」・「論文」の3類型に分類されます。主な分類基準は記事の目的・記事が生む価値は何かです。

類型	記事の目的・価値
学習ノート	筆者による理解の復習・確認やアウトプットの練習のために書かれる。
教科書	読者に対する知識の提供を主な価値とする。
論文	単なる知識だけでなく、アイデアや技術の新規性を提供する。

本来の研究論文には「査読を受ける」という重要な特徴がありますが、上の3類型における「論文」はこの特徴を無視しています。より良い名前を考えたいのですが、新規性という軸で「教科書」と対比されるものとして「論文」しか考えつかなかったのでこのようになっています。

この分類において、教科書・論文は読者に対して知識・知見という形で価値を提供することを主な目的としていますが、学習ノートはそうではありません。学習ノートを書くことの恩恵を受けるのはそれを書いた人自身です。典型的には、学習ノートはそれを読んだ人が価値を受けるものではなく、その点が学習ノートと教科書の境界であると考えています。

なお、この記事では公式ドキュメントのような一次情報は以上の3類型に含んでいません。

3類型とエンジニアの相性

記事を受け取るエンジニアの側を初心者・中級者・上級者の3つに雑に分類した場合、これらのエンジニアと3類型の記事の相性は次の表のようになるでしょう。○は相性が良い（記事から価値を受けられる）ことを示し、×は相性が悪い（記事から価値を受けにくい）ことを表します。

	学習ノート	教科書	論文
初心者	×	○	×
中級者	×	○	○
上級者	×	×	○

学習ノートが全て×となっていますが、これはそもそも学習ノートは読み手に価値を与えるものではないと定義しているので当たり前のことです。×と書くと学習ノートが悪いものであるような印象を受けるかもしれませんが、そのような主張をしているわけではないのでご安心ください。

ただし、初心者同士が「ノートを見せ合う」かのように、他の初心者の学習ノートを参考にできる場合もあるかもしれません。この場合はそれが「学習ノートである」と認識していることが前提です。学習ノートとして書かれたものを教科書だと思って参考にすると痛い目に遭うでしょう。

教科書は知識を提供するものなので、初心者や中級者に対して有効です。上級者の場合、知識はすでに知っているので教科書から新たに得られる価値はあまり多くないでしょう。ただし、上級者が教科書類型の記事をSNSでシェアしている様子は結構見られます。これは、その記事を利用してその上級者自身が新たな価値を提供する行動です。教科書や論文はクオリティに幅がありますから、クオリティが良いものを選定・紹介することはコミュニティに対する価値の提供となります。

上級者に内容自体に興味を持ってもらうには、論文類型の記事が必要です。つまり、上級者が記事から新たな価値を受けるためには単なる“知識”にとどまらない“知見”が必要だということです。知見というのは、具体的には新たな概念や考え方、独自の考察などです。

中級者でも論文類型の記事から価値を受け取ることはできるだろうという考えから中級者と論文の相性は○としています。一方、こういった知見は多くの場合知識をベースとしているため、知識がおぼつかないであろう初心者については論文との相性を×としています。

初心者による技術記事執筆のすすめ

初心者が技術記事を書くことの是非についてはよく議論の対象となります。また、初心者が書いた記事を中上級者が批評・批判することについても、セットで議論になります。

筆者の考えでは、まず大前提として記事を書くのは自由だから好きなものを好きなように書けばいいと思っています。ただし、書いたものが価値を発揮するかどうかは別の話です。もし自分が書いた記事が何らかの意味で価値を発揮してほしいのであれば、気をつけなければならないことがあります。

おすすめは学習ノートから

お察しの通り、初心者が書く記事としておすすめのものは学習ノートです。学習ノートを書くということは、自分が学習した内容をアウトプットすることです。メモ書きのようなものでも、しっかり章立てしても構わないでしょう。

ただし、先述の通り、学習ノートはそれを読む人に価値を与えるものではありません。筆者の意見では、自分が初心者であると思っている人が記事を通して他人に知識を与えようというのは、残念ながら自分を過大評価しすぎです。他人に知識を与える記事（すなわち教科書類型や論文類型に分類される記事）を書けたならば、（少なくともその分野では）もはや初心者ではないのではないでしょうか。

学習ノートは、読む人に価値を与えないからといって、無価値ではありません。学習ノートの価値はそれを書いた人自身が受け取ることになります。自分が学習したことを言語化することは自分の理解を促進する助けとなるはずです。さらに、中級者以上の人に読んでもらって間違いを指摘してもらうことで、自分の理解を改善することができます。

学習ノートと間違いの指摘

ここで「間違いを指摘」というワードが出てきました。前提として、記事が間違っているからといって、間違いの指摘に付随して人格攻撃のハラスメントを行うことは論外です。そのような行為をこの記事では一切擁護しません。ただし、筆者は、間違いを指摘することそれ自体は善いことであると考えています。間違いを指摘することは論理的なコミュニケーションに不可欠だし、間違った記述が正しくなることは記事の価値を向上させるからです。

学習ノートの場合、人によっては、記事を公開することの目的として間違いの指摘を受けることも含まれるでしょう。むしろ、書いたものをインターネットに公開する・公開しないという選択肢がある状況で公開するという選択肢を取った以上、間違いの指摘を含むフィードバックを受け入れるつもりであると捉える方が自然です。

フィードバックと言えば間違いの指摘だけでなく良い点の指摘も含まれるはずですが、学習ノートに対するフィードバックを受ける場合、良い点よりも悪い点（間違い）ばかり指摘される傾向があることは否めません。しかし、これは初心者が書いた学習ノートに特有の話ではありません。熟練のエンジニアでさえ、コードレビューをする際に悪い点ばかり指摘してしまいがちであり、意識してコードの良い点を指摘しようという話題がたまに見られます。

学習ノートを書くときに気をつけると良いこと

学習ノートに対するフィードバックを受けるのは有意義なことですが、やり方によっては、必要以上に不快な思いをすることを事前に予防することができるかもしれません。

筆者の考えでは、書き手の意図と読み手の期待がずれた場合に不幸なフィードバックが発生します。具体的には、書き手が学習ノートとして書いたものを、読み手が教科書だと思った場合です。教科書は読み手に知識という形で価値を与えるものですから、教科書の内容が間違っていた場合はコミュニティにとって有害です。コミュニティにとって有害なものを正すために指摘を書くのは善行か悪行かでいうと善行でしょう。教科書の内容が間違っている場合、それが批難されるのは当たり前のことです（繰り返しになりますが、その際に人格攻撃や、あるいは非論理的な指摘を付随させるのはだめです）。

せっかく頑張って記事に理解をまとめたのに淡々と間違いを指摘されて不快になるという思いを予防するためには、自分は学習ノートを書くのだと意識を明確にし、読み手にこれは学習ノートであると伝わるようにしましょう。別に、この記事を引用して「学習ノート」という言葉を使えというわけではありません。「学習したことをまとめました」とか、学習ノート類型の記事であると分かるような言葉を書いておくとよいでしょう。そうすれば、良い人なら、間違いを指摘するにしてももう少し優しく指摘してくれるでしょう。もっと優しい人は褒め言葉も書いてくれるかもしれません。もしまだ厳しい指摘をしてくる人がいたとしたら、その人は記事の意図を正しく理解できない人ということになります。そのような指摘が飛んでくる事故を完全に防ぐことはできませんが、そんな人から来た指摘だと思えば少しは溜飲が下がるのではないでしょうか。

初心者が主に参考にするのは教科書類型の記事であるという都合上、初心者が記事を書く際にはついつい教科書のような体裁の記事を書いてしまいがちではないでしょうか。筆者は、いくら初心者といえ、知識が伴わないまま教科書のように見える記事を書くことには厳しい立場を取っています。前述の通り、内容の間違った教科書は有害だからです。特に、別の初心者が、教科書としてふさわしくないものを教科書だと思って参考にしてしまうのは困ります。

ただし、初心者ならば、知識が間違っている・足りないことは問題ではありません。そのような状態で、教科書類型の（ように見える）記事を書くことだけが問題です。

だからこそ、初心者が記事を書く際には、記事の意図（学習ノート類型の記事として書いたということ）が伝わるように書くのがよいと思っています。フィードバックを受け付ける気があるならば、それは記事を通した書き手と読み手のコミュニケーションです。読み手から適切なフィードバックを期待するならば、書き手の側からも適切に情報を提供する責務があります。これは技術的な知識の多寡にかかわらずにできることであり、技術コミュニティというオープンな場で記事を通してコミュニケーションする際のマナー（この言葉はあまり好きではないのですが）であると思っています。だからこそ、初心者が記事を書くときの心構えとしてお勧めします。

このように「この記事はどのような意図で書かれたのか」ということを記事中で明らかにすることは、読み手に記事の意図を正しく理解してもらうために重要です。そして実は、これは初心者に限らずどんなレベルの記事においても基本的かつ重要なことです。「対象読者を明記する」といったことも記事の意図を伝える手段として優れています。ですから、初心者のうちから「記事の意図を読み手に伝える」ことを練習しておくと有利です。

教科書へのステップアップ

少し前に述べたように、教科書に類する技術記事が書けるようになれば、初心者を脱却したと言えるでしょう。それだけに、記事を教科書類型のものとして世に出すのは一定の覚悟が必要です。初心者への悪影響などを考えると教科書は間違っているべきではなく、だからこそ学習ノートよりも厳しい目で記事が見られるのは仕方のないことです。

もちろん、どんな内容の教科書を書くのも自由です（内容が間違っていれば当然批判に晒されますが）。しかしやはりそれは、どんな内容の記事でも価値が認められるということを意味してはいません。教科書の価値というのは、冒頭で述べたとおり読み手に知識を提供することです。筆者はどちらかと言えば、コミュニティにこのような価値を提供できること自体が記事を書く動機になるタイプです。また、このような記事の存在は書き手の知識レベルを保証するものでもあり、書き手の名声に還元されるという点での価値もあります。これを目的にしている書き手もいるでしょう。

ただし、教科書にはクオリティの高低があります。伝える知識が間違っていないこともクオリティの一部ですが、多くの場合教科書類型の記事の内容は二次情報であり（だからこそ上級者は教科書類型の記事にあまり価値を感じません）、知識そのものよりも「まとめ方が上手かどうか」「読者の理解をいかに促すか」「出典を明記しているか」といった知識そのもの以外のことが記事のクオリティに影響します。例えば、公式ドキュメントの内容そのままで付加価値が無い記事などは、内容が間違っていなければ価値がマイナスとまでは言いませんが、公式ドキュメントを読めばいいのですからコミュニティに価値を提供しているとは言えません。コミュニティに価値を提供したいと思うのならば、何らかの付加価値を与えることを考えましょう。

そうなると、教科書類型の記事を書くことを志すならば、まず自身の知識を確たるものにしなければなりません。特に、出典の明記や読者の理解を手助けするといった付加価値を付けるのであれば、記事に書かれる内容以上の知識を書き手が有していなければなりません。目安として、記事に書く内容の正しさを（丸暗記・うろ覚えなどではなく）根拠を持って説明できるのであれば、その内容は価値ある教科書となりうるでしょう。

ところで、教科書といっても、必ずしも重量級の記事である必要はありません。「メモ書き」とか「体験談」のような記事も、この記事の3類型では「教科書」に分類されると考えています。学習ノートだけでなく教科書類型の記事を書けるようになりたければ、こういった記事から始めるのが良さそうです。

よく「自分用メモ」みたいな記事が見られることがあり、中上級者でも技術記事を書く目的として「将来の自分のためにメモを残すこと」を挙げる人が多く見られます。それでも、この記事ではこれらを（学習ノートに近いとはいえ）「教科書」類型に分類します。なぜなら、こういった記事もあくまで知識を読者に（もしかしたら将来の自分に）提供することを目的としていて、そして公開されているからです。メモ書きを公開するなとは言いません。メモ書きを公開する理由は、自分以外の人を救うかもしれないからではないでしょうか。それはコミュニティに資する善いことですから、どんどん公開しましょう。

メモ書きや体験談といった記事は、安定したクオリティを出せるので教科書類型の執筆の入門におすすめです。例えば、特定のエラーを解決した際の記録などがよいですね。まず、「あなたが経験した」ということは間違いなく事実であり、前述の「記事に書く内容の正しさ」を満たしています。あなたが経験したことを「私が経験しました」と書くのは文句のつけようが無く正しいでしょう。学習ノートから教科書にステップアップする際にハードルになりやすいのが内容の正しさをきちんと保証することですから、それを経験でクリアできるのは大きいですね。

これらのタイプの記事が知識そのものに加えて提供する付加価値は、特定のニッチなシチュエーションに対する解決策を具体的に提示し見る人の時間を節約する（自分で調べる必要が無くなる）ことです。調べた過程が詳しくメモされていて閲覧者が一次情報を辿れるようになっていればさらに付加価値が高まるでしょう。初心者を脱する頃になれば、面倒なシチュエーションの一つや二つ経験していてもおかしくはありませんから、記事を書くチャンスとなります。

論文類型について

3類型の3つ目として提示されているのが論文類型です。上級者の興味を引くのは多くの場合この類型の記事でしょう。明らかに初心者向けではないので軽く議論するだけにしておきます。

上級者は、単なる知識はもう知っているので価値を感じません。それよりも、まだ知らない考え方やアイデアに興味を持ちます。そのために必要なのが新規性あるいは独自性です。新規性のある内容が載っている記事はコミュニティに対してもとても有益で、高い価値があります。

アイデアレベルの新規性を生み出すには、あなたが仕入れた知識を並び替えたり噛み砕いたりするだけでは不足です。あなた自身が独自の考察をすることで新規性が生まれるのです。

記事の冒頭に書かれていたことを思い出してください。

そこで、この記事では技術記事に対する3類型の分類を提案し、それを基に技術記事の執筆について考察します。

ご注意: この分類やこの記事の内容全般は筆者の私見であり、唯一の正解であると主張するものではありません。

「提案」「考察」「私見」といったワードがあります。これらのワードは、この記事が論文類型であるという主張です（少なくとも筆者は論文類型を目指して書いています。この記事は技術記事とは少し違いますが）。論文類型となるためには、こういった要素が不可欠です。

ただし、ただ妄想与太話を綴るだけでは価値のある記事とは見なされないでしょう。読み手が納得して何かを得て初めて、記事は価値があるものとなります。そのために、必要なだけの仮定を設定し、それと事実を組み合わせて論理を展開することで説得力を生み出します。そうすることで論文類型の記事を 書くことができます。 書くことができると思っていますが、筆者は大学院に2年居ただけなので比喩とはいえ論文と名をつけたものの書き方を指導をする立場にありません。ともに頑張りましょう。

読み手から見た3類型

ここまでは書き手（特に初心者の立場）から考察してきましたが、記事の読み手の立場としても、このような記事の類型を意識することには意味があります。技術記事を見て、それがどのような類型に属するのか考えましょう。類型が分かりやすい記事ならば優れた記事である確率も高いでしょう。

記事が学習ノートだと思ったならば、知識を得るために読むべきではありません（特に、知識を得るために記事を読むことが多い初心者こそこの意識は重要です）。間違いを見つけたとしても、指摘をする際は気をつけたほうがよいでしょう。学習ノートならば、正しい内容を書くことは書き手の義務ではありません。間違いを指摘する唯一妥当な目的は書き手の学習を支援することです。

逆に、教科書だと思ったならば、ぜひそこから知識を得ましょう。間違いを見つけたならば、修正してもらうことを目的として間違いを指摘してもよいでしょう。

論文類型の記事に興味を持ちそこから何かを得られるならば、技術者としてなかなか高いレベルを持っていると言えます。ただし、このような記事はただの知識では無い以上、著者の考えや仮定が現れがちです。必ずしも自分の考えに合った内容であるとは限りません。そういうものだと思いましょう。

まとめ

この記事では技術記事を比喩的に「学習ノート」「教科書」「論文」の3類型に分類し、特に学習ノート・教科書の両者に対して書き手・読み手がどのような立場を取るべきか考察しました。筆者は、初心者・中級者・上級者といった異なる立場の人たちが共存する技術コミュニティにおいて、全ての技術記事を一緒くたに扱って議論することは難しいと考えます。この記事の類型が必ずしもベストだとは思っていませんが、皆さんが技術記事について考える際には技術記事を分類することについて意識してみるのはいかがでしょうか。