「技術力の高い記事」の技術力ってなんなんっすか！？ マネーフォワードの技術広報が2年連続100記事レビューした経験から考察した結論
技術力の高い記事の技術力ってなんなんっすか？
タイトルは面白いって何なんすか!?問題――センスは「考え方」より「選び方」で身につく Kindle版のオマージュです。
この記事はマネーフォワード 関西開発拠点 Advent Calendar 2022 2日目です。
今朝、日本代表が下馬評を覆してドイツ・スペイン・コスタリカの厳しいグループリーグ突破をしましたね。
ぼくも日本代表を見ていた多くの方と同じくマネーフォワードのサッカー好きなメンバーと盛り上がってました。
いやーいい試合でしたねぇ……。
閑話休題。
突然ですが皆さん、技術記事を書かれてますか？
きっとこの記事を読もうとするくらいなので日々書いているか読んでいるかされている方が多いのだと思います。
技術記事を書いているときにふと「技術力の高い技術記事を書きたいがどうすればいいんだっけ？」と考えたことが1度くらいあるのではないでしょうか？ぼくは仕事柄もあってほぼ毎月ペースで発生します。
この記事は技術力が高い技術記事が書ける…ようになるわけではありません。
大事なことなのでもう一度いいますが、この記事を読んでも技術力の高い技術記事は書けません。
この記事は技術記事を書く技術力を考察、分析することで、普段書いている技術記事の文章力を高めるにはどうすればいいか？どのような観点でレビューをするといいのかをふりかえったり、読んだ人が「いや自分はそうは思わない」「ここの部分は自分たちも同じだ」と考えるきっかけになってほしいと思い執筆しました。
想定読者
技術ブログを運営しているがソフトウェアエンジニアリングの技術に詳しくない方
なんとなく技術ブログの運営をすることになったが他のエンジニアに指摘するのが怖い方
読んだ後こうなってほしいと思う期待値
読者が読んだあとで自分たちにとっての「技術力の高い技術記事の条件」が説明できる
読者がどうすればよい技術記事のレビューができるのか？を考えるきっかけが持てる
前提
この記事内では以下の前提であることに留意してください。
エンジニアとはソフトウェアエンジニアを指す
技術力が高い記事 == 想定読者に知りたい情報を提供できている記事
PV数が多い != 技術力が高い技術記事
あくまでも技術力が高い記事の技術力とはなにか？を定義し、考察していくための記事です。
技術力が高いに語弊があるワードセンスになっていますが、うまく単語を定義できなかったのでこのままでいかせてください。
ライティングスキルでもあるけどソフトウェアテクニカルでもあるという中間の概念を定義できませんでした。ふわふわした定義ですまん。
そもそも技術力が低い技術記事とはどういう状態か？
まず技術力の高さを知る前に、逆の状態である技術力の低い技術記事とはなんであるか？を確認したいと思います。
一般的によく見聞きする技術力が低い技術記事とは以下の特徴を持つと仮定します。
個人の作業ログである。
やってみた系の技術記事である。
少し調べればわかるTips系の記事である。
ですが、この特徴は本当に「技術力が低い」技術記事に当たるのでしょうか？
例えば、以下の技術記事は作業メモに分類されるブログですが、ぼくは技術力が低いとは感じませんでした。
なぜそう思わないかと考えたときに次のような条件があると考えます。
先進性のある議題であり、技術記事のテーマがありきたりではないこと。
一次情報を参照し、情報を咀嚼して概要や解説をわかりやすくまとめていること。
情報が整理され、構造化されていること。
つまり作業ログであっても十分に技術力が高い技術記事になっています。
また、上記を補強する情報として、クラスメソッドさんが運営される技術系メディアの名前が「クラスメソッド発「やってみた」系技術メディア」 であることも多少考慮に影響しています。
やってみた系や作業ログが課題なのではなく、それらのラベルが貼られた技術記事のネガティブな共通項を指して「技術力が低い」と評価していると判断しました。そこで以下の仮説を立ててみました。
仮説: 技術力の低い記事とは「読んだあとの納得感」ではないか
先程述べたように「やってみた系」や「作業ログ」、「Tips系」の記事であっても技術力が高い技術記事はあります。では、それはたまたま「技術力が高い技術記事」だったのでしょうか？その可能性も十分にあります。
基本的に技術力が高い記事のほうが絶対数は少なく、反して技術力が低い記事のほうが多い傾向があると考えます、これはエンジニアの技術レベルのピラミッドに依存するため、異論はおそらくないでしょう。
そこでより具体的にイメージするため、「技術力が低い技術記事だ」と感じるストーリーを書き出してみました。
ストーリー1: エラーを調べたが役に立たなかった
とあるエラーメッセージで検索をおこなう
該当記事に到達する
「なんだかわからないけど色々触っていたら再現しなくなりました。」と書かれている
エラーメッセージが何故おこっているのか？を知りたいのに原因が書かれていない！と憤慨する
この技術記事は技術力が低いと判断する
ストーリー2: とある機能を採用検討しているが欲しい情報に到達しなかった
GoのXXX機能について検索をおこなう
該当記事に到達する
「チュートリアル通りにやればできました」と書かれている
XXXを試してみた感想や困った点、助かった点が知りたいのに書かれていない！チュートリアル通りにして動くのは当たり前だろ！と憤慨する
この技術記事は技術力が低いと判断する
この2つのストーリーは実際にあったわけではなく、こういうケースがあるのではないか？というぼくが考えて書き出してみた事例です。実際にこういった書かれ方をしている技術記事を非難する意図がない点に留意してください。
技術力が低いと感じる技術記事には様々なパターンがあると思いますが、読者が判断する際に共通しているのは「知りたい情報に対する情報量が増えなかった」ではないかと考えました。
ここで重要なのは情報量が増えていないことです。「知りたいことを知ることができなかった」は含みません。
例えば、自分が望む結論でなかったとしても、それは「自分が知りたい情報がここにはない」と知ることができます。
この情報自体は読者に「自分が知りたい知識はこの情報圏にはない」ことがわかり、異なる方向で調べることができます。ですので、「ない」という情報が増えている状態です。それでは技術力が高い技術記事とはどういう状態なのでしょうか？
技術力が高い技術記事とは？
年間で100記事ほど会社の技術記事をレビューしてわかった事実がいくつかあります。
レビュー依頼をされても修正することがほぼない記事が存在する。
レビュー依頼されて修正コメントを大量に残す記事が存在する。
修正することがない記事の投稿者はレビュー傾向として修正依頼をすることが少ない。
レビュー指摘の少ない投稿者の技術記事には以下の3つの傾向があることがわかりました。
価値のあるテーマになっている
技術記事の構成が良い論文の構成と同じになっている
著者の独自性が情報に付加価値を生み出している
ここからは推測ですが、レビュー指摘が少ない投稿者はこれらの傾向を踏まえた記事を書き慣れているのではないでしょうか？
また投稿先のトンマナ（トーン&マナー）を知っているなどの諸条件も関係していると考えます。
それらの条件があることは考慮しつつも、それぞれの傾向について考察と分析をしていこうと思います。
価値のあるテーマになっている
この傾向には以下のような特徴があると考えました。
先進性（新規性）: 情報の希少価値が高いこと
専門性（独自性）: 深く時間をかけて調べないとわからないこと
革新性: いままでに可能でなかったことを可能にしていること
エンジニアの関心は大きくこの3つに集約されると推測されます。
言葉や分類は多少異なりますがDroidKaigiのDroidKaigi プロポーザルのすゝめにもほぼ同様の概念が出てくるため、おそらくそこまで外れていないと考えています。
※これらを満たしていないからといって、技術力が高くないわけではありません。あくまでも技術力が高いと考える技術記事に共通する傾向です。
技術記事の構成が良い論文の構成と同じになっている
次にこちらの傾向では、以下の構成を満たすケースが多く見受けられました。
背景・目的
課題定義
仮説検証
結果
考察
結論（まとめ）
この構成をみて、よい論文の書き方や構成と親和性がありそうだと気づきました。
技術記事は小説ではないので必要なのは「起承転結」ではなく「序破急」であることが求められ、そのためには主張（目的や背景、あるいは課題）に対する一貫したストーリーが必要となるのではないかと考えます。
一貫したストーリーにするためには明確な軸となる「背景・目的」が必要です。目的を達成するための障害が課題であり、課題を解決するための仮説検証と結果、最終的に結果から得られた情報を考察し自分なりの結論に至るという導線を辿るからです。
そして、想定読者とはその背景や目的に共感する人となります。
端的にいうならばよい技術記事とは「読者が価値を感じる記事」のことです。価値を感じた結果、面白かったや学びがあったという感想につながっていると分析しました。
つまり想定読者のペルソナが明確であり、読んだあとどのように感じてもらえるかイメージできることがとても重要で、イメージの解像度が低い場合、価値を届けられる可能性は大きく落ちると予想されます。
例えば、想定読者の具体的なイメージがなく「○○という人に価値があるだろう」とする場合はほぼ例外なく推測であり、解像度が荒い状態といえます。
最低でも「この人に価値がある」と言い切れる状態になるまで解像度を上げる必要があります。
この対象が「かつての自分」でも問題ありません、重要なのはかつての自分と今の自分の差分を言語化できることです。
なぜ書こうと思ったのか？を因数分解すると見えてくるとぼくは考えます。もちろん、これは自発的に書こうと考えられた場合に限定されます。
上司や同僚に書いてほしいと言われて書くときには見つけ出すのは難しいと思うので、「なぜ自分に書いてほしいと思ったのか？」をヒアリングしましょう。書いて欲しいと依頼した際の期待値の中に答えにたどり着くヒントがあるはずです。
反面、ノルマには数字を達成するためだけの投稿数の水増しとなるこのイメージがない、あるいは誰もわかっていないケースがあります。そういった場合は「なぜ書かなければいけないのか？」から問いかけるのがよいでしょう。
著者の独自性が情報に付加価値を生み出している
この内容に関しては以下の資料が端的に表現していたので引用させてもらいました。
論文の価値は、いかに自分なりの視点でテーマが設定され、どの程度説得力のある結論が得られたかという独自性で評価される。
この資料の対象は論文を前提としていますが、技術記事も特徴として同様の理論が当てはめられると考えました。
技術記事に掲載されることが情報だけなら一次情報である公式ドキュメントやコードが掲載されているGitHubのリポジトリを読めば事足りることがほとんどでないかと思います。
ですが、技術記事を書く、読む行為を行うのはそれ以外の付加価値・付加情報を知りたいと感じているからではないでしょうか？
例えば公式の情報だけでは不足する知識や前提がある、特定の状況下や特殊な条件を満たすなどがその付加価値足り得るのではないかと推測しました。
一次情報はその媒体が持つ特徴として経験や感情のような情報を削ぎ落とします、あるいはその傾向が高いでしょう。そしてそれはドキュメントの性質を考えたときに正しい戦略です。
ですが、一次情報ではノイズになる情報も、技術記事では逆にこのノイズこそが価値を生み出すことに貢献しているのではないかと考えました。
Case: マネーフォワードの技術記事 in 2022
以上の考察から改めて、3つの特徴に当てはまると感じた2022年に投稿されたマネーフォワードの記事をどの特徴に当てはまったか？を記載してピックアップしてみました。一覧から該当しそうなタイトルをピックアップしたり内容から選出しています。（なにせほぼ全ての技術記事をレビューしてるので！）
並びは順不同です。
課題に対する前提を整理し、斬新なアイディアを実装する内容が記載されており「革新性が高い」。
丁寧に動作検証をおこない、わかりやすく解説しているため「専門性が高い」。
国内でのOpenrestyに関する技術記事が少なく希少性が高く「先進性が高い」。
Android 13発表の2ヶ月後に変更点に対する対応を簡潔にまとめており「先進性・専門性・革新性が高い」。
特定の状況下でのユースケースに限定し、詳細を深めているため「専門性が高い」。
いままでできなかった、ストレスに感じていたことを技術で解決しているため「革新性が高い」。
とあるライブラリの紹介だが想定読者と提供する価値提供のレベルが高く「専門性・革新性が高い」。
将来起こり得るであろう課題に対して先回りでの対策を行っており、想定読者が気になりやすい関心事をテーマに据えており「先進性が高い」
想定読者の課題に対する解像度が高く、その解決策の応用範囲がが高いと感じられるため「専門性が高い」。
これらの意見は事実である保証はありません。まさしくただの感想です。
ですが、レビュアーとして基準点を明確にした状態で記事を見直したときにこのように感じた…といえることはレビュアーとして大きな意味を持つと実感しました。
この記事の良さがどこにあるのか？を意識し、書き出すことでより深く記事の内容を理解でき、技術広報として技術ブランディングを押し出す際に「ここが目玉です！」を伝えられるのは大きな武器になるでしょう。
技術広報でなく投稿者にも「このような要所を押さえるとよい」という指標を手に入れることができると考えます。
まとめ
技術力が低い・高いに関する考察と分析をしたことで、技術記事の価値をどのようにして届けるか、届ける際に持っておくべき基準点はなにかを理解できました。
おそらく、この基準点はテクニカルライティングなスキルに分類されるでしょう。
技術記事に留まらず、イベント登壇のスライドやカンファレンスのプロポーザルにも貢献することができると感じていますし、実際に登壇スライドのレビューを依頼された際にこのような観点で見ていることが言語化されました。
レビュアーとして「もっと良くなるにはどうすればいいだろう？」を常に問いかけることで、なにが良くてなにが足りないかを意識し、どの要素が足りていないのか？を提示することができるようになったと感じています。
「価値のあるテーマになっている」に関しては専門的な知識、あるいは最新の状態を把握している必要があるため、非エンジニアには難しいかもしれません。
実際ぼくも専門分野外の技術領域のAI/MLやSRE、インフラに関しては技術的にあまり言えることがありませんが、その技術領域に詳しいチームメンバーや記事を書かれた上司の方にレビューをお願いすれば、ある程度担保することが可能です。
アドベントカレンダー開始直前（11月30日 16時時点）で関西拠点の2日目に登録したのでなにを書くといいか？悩みました。
そこでふと普段なんとなく考えている「どうすればよい技術記事のレビューができるのか？」を考えるきっかけが持てるような記事を書こうと思い、本記事を執筆しました。
もし読んだ方が「とても参考になった」「自分たちはこう考えている」などあればぜひブログに書いて公開してもらえると嬉しいです。
