伝えたい人に届ける技術記事の書き方

こんにちは、リファクタリングが大好きなミノ駆動です。
この記事は READYFORアドベントカレンダー2021 、初日の記事です。

なにこれ？

苦労して執筆した技術記事は、伝えたい人にしっかり伝えたいですよね。
また、最後まで読んでもらいたいですよね。

一方で、構成などに課題があって、伝えたい人になかなか伝わらないことがあります。

この記事は、伝わる記事の書き方について、私の個人的なノウハウを書き記したものです。

これからアドベントカレンダーの記事を執筆される皆さんにとって、少しでもお役に立てられれば幸いです。

この記事のゴール

以下の理解を得ることをゴールとします。

• 以下2つの要件を踏まえた記事構成を心がけること。
  • 構成要件①：技術を紹介する上で最低限説明の必要な内容を網羅すること。
    • 特に課題をしっかり伝えること。
  • 構成要件②：読み手が段階的に理解しやすい順番になっていること。
• 告知の仕方を工夫すること。
  • アクセスの多い時間帯を選択すること。
  • ツイートの文面を工夫すること。

筆者の実績は？

説得力を持たせるために一応記載します。
2021/11/23時点の実績です。

• 全記事数 ： 7
• 最大LGTM : 1904
• 最小LGTM : 458
• 総獲得LGTM : 7725
• 平均獲得LGTM : 1103

こちらの分析によると、300LGTM以上獲得した記事は、Qiita全体で0.22% とのこと。

本題

前置きはこの辺にして、ここからが本題です。

この記事で解決したいこと

QiitaやZennなどの技術投稿サイトなどでは、「良いことが書かれているのに、ちょっと分かりにくいな…。もうちょっと工夫があると伝わりやすいんだけど」と感じる記事を見かけることがあります。

そのとき、例えば以下のような課題を感じます。

• 解決したい課題がはっきりしない。
• 最後まで読まないと主張が分からない。途中で投げられやすい。
• 論理があちこちに飛んで、読みづらい。よどみなくサラサラと読めない。

課題の原因

こうした課題には、以下のような原因があると考えます。

• 基本的に書いておくべきことが抜けている。
• 読み手が段階的に理解可能な順番で書かれていない。

解決手段 ： 伝えるための基本構成

• 基本的に書いておくべきことをしっかり書く
• 読み手が段階的に理解しやすい順番で書く

これらを踏まえるために、私は構成が以下となるよう執筆します。

• タイトル
• 概要
• この記事で伝えたいこと　←★重要★
• 解決したい課題　←★重要★
• 課題の原因
• 課題を解決する技術、手法
  • 技術、手法の概要
  • 技術、手法の効果
  • 課題がどう解決されるか
  • 応用事例のカタログ化
• 留意点、デメリット

もちろん執筆内容によってはこの構成通りにはならない、書きにくいものもあると思います。
ただ、自分としてはこの構成を基本としています。
応用させるにしても、この構成がベースです。

私が執筆した以下2つの記事も、同様の構成です。
本記事の説明と見比べて読み進めることをオススメします。

大前提 : 技術で解決したい課題を明確に

技術は何らかの課題を解決するための仕組みです。

ありがちなのは、技術の紹介だけになっている記事。
課題の記述がなく、「一体何の役に立つんだろう…」と、読者が迷子になってしまいます。

記事を書き始める前に、まずは対応する課題を整理しましょう。

この、「課題 : 技術」は、記事全体にわたって考慮すべき重要な対比関係なので、よく覚えておいてください。

では、各構成の要点を以下に説明します。

構成1 : タイトル

Qiitaのガイドラインにもタイトルの付け方について説明がありますが、私のオススメは課題と解決技術が分かるタイトル文言です。

例えば僕の記事はほとんどが 「（解決技術）で（課題）を爆殺する」 のフォーマットになっております。

一方、「○○について」といったタイトルの記事をたびたび見かけます。
しかし、その技術の何について言及しているのか分かりにくく、良いタイトルではないと考えます。

構成2 : 概要

本記事の冒頭「なにこれ？」にあるように、記事の概要項目です。

概要といっても単に簡素化抽象化した事柄ではなく、解決したい課題と、対応する解決技術の概要を書きましょう。

技術記事を読みに来る人は、興味本位で読みに来る人もいますが、多くは技術的な困りごとがあって記事を探しに来る人だと推察されます。

冒頭で課題をハッキリさせておけば、まずそこで読み手にリーチしやすいでしょう。

構成3 : 【重要】この記事で伝えたいこと

記事の主張や要点を列挙します。
次の例をご覧ください。

• 例1：「単一責任原則で無責任な多目的クラスを爆殺する」より
• 例2：「関心の分離を意識した名前設計で巨大クラスを爆殺する」より

ここで列挙したことが、読み手にとってのゴールになります。
ゴールを意識させることは、読み手に迷わせない、最後まで読んでもらう上で超重要です。

短い文章であれば読み手はあまり迷いません。
しかし技術記事は大抵それなりに大きなボリュームになります。
長大な文章は、えてして主張や大事なポイントが分かりにくくなるものです。
「筆者は何を伝えたいんだろう…？？」と読み手が迷ってしまうかもしれません。
途中で投げられて最後まで読まれなくなることも懸念されます。

登山でも仕事でも、どこがゴールなのか分からない状態では進むにも進めません。
ゴールがハッキリしているからこそ、人はそこに向かって歩みを進められます。

技術記事も同じです。
ゴールとなる主張を冒頭でしっかり列挙しましょう。

構成4 : 【重要】解決したい課題

繰り返しになりますが、技術は何らかの課題を解決するための仕組みです。
ここで課題を詳細に言語化します。

課題がどれだけシンドイか、具体例も絡めながら説明できれば、解決技術とのギャップが大きくなります。
ギャップが大きくなると解決技術の利点が浮き彫りになり、読者に伝わりやすくなります。

構成5 : 課題の原因

何が原因で課題が生じているか説明があると、より説得力が増すでしょう。

構成6 : 課題を解決する技術、手法

ここからやっと解決技術の話を記述します。
下記いろいろ列挙していますが、例の一部に過ぎません。
書き手の工夫次第なパートです。

構成6-1 : 技術、手法の概要

技術、手法についての紹介です。
どういった技術なのか概要を説明します。

構成6-2 : 技術、手法の効果

どんな効果があるのか明確に言語化すると、読者が理解がより進むでしょう。
設計パターンを例にすると、以下のような効果を説明できます。

• Strategyパターン : 条件分岐の低減
• First Class Collectionパターン : コレクション操作を高凝集にする

構成6-3 : 課題がどう解決されるか

技術を適用した結果、対象課題がどう解決されるのか解説しましょう。
ギャップの解消が見える化され、解決技術の利点が伝わりやすくなります。

構成6-4 : 応用事例のカタログ化

応用的な使い方について、多くのバリエーションで具体事例を列挙すると、カタログ的に参照したい読者を助けることになります。

応用ノウハウがあるならば、挙げられるだけなるべく多くの事例を列挙できると良いでしょう。

構成7 : 留意点、デメリット

人は未知のものに遭遇した際、多かれ少なかれ不安感を抱くものです。
「この技術は使えるものなのか？使って大丈夫なものなのか？」と。

安心と信頼に応えるためにも、使用上の留意点やデメリットも書きましょう。

あらゆることを解決する、デメリットのない万能な技術は存在しません。
また、同じ課題に関して、複数の解決手段があったりもします。

可能であれば別の解決手段も提示し比較した上で、デメリットが発生するケースや留意点を付記するのが、読み手に対して正直で真摯であると考えます。

ここまでが記事の構成です。
次は告知の方法です。

---

告知の方法

ちゃんと告知して人に認知されることは重要です。

告知する時間帯

例えば極端な話、皆が寝静まっているようなウシミツアワーに記事を公開し、Twitterで告知して、見てくれる人はいるでしょうか。
ほとんど誰の目にも触れられず、TLに流されてしまうでしょう。
大変な機会損失ですね。

逆に、多くのユーザーがTwitterにアクセスする時間帯があります。
それが12:00です。
12:00は昼食がてらTwitterを閲覧するユーザーさんが多いと言われています。
この時間帯を使わない手はありません。

また、「17:00〜22:00にかけてアクセス数が伸びる」という分析結果もあるようです。

したがって、自分は以下のように告知しています。

• 12:00：記事公開、Twitterで告知。
• 17:00：12:00の告知ツイートを自分でRTし、ブーストする。

【注意】ありがちで陥りがちな告知時間

頻繁に見受けられるのが、9:00-11:00、14:00-16:00といった中途半端な時間帯での記事公開と告知です。

この時間帯は多くの人が働いており、記事があまり目に止まりません。
非常にもったいないので是非避けてほしいところです。

告知の文言

告知の文言も工夫しましょう。

記事を書きました。
単一責任原則を具体的なコードで解説。

「技術に興味はあるけどビジネスには興味ないし」的な考えを持っていると単一責任設計が困難な理由も説明します。

「単一責任原則で無責任な多目的クラスを爆殺する」https://t.co/F39YMZnXjh #Qiita

— ミノ駆動 (@MinoDriven) December 8, 2020

「記事を書きました」で自分が執筆したことを伝える

「記事を書きました」は意外に重要です。
この記述がなく、単に記事のリンクとタイトルだけをツイートすると、読み手はどう感じるでしょうか。

「誰か他の人が書いた記事なのかな？」と勘違いしてしまう懸念があります。
非常にもったいないです。

自分が書いた記事であることを明確に表明しましょう。

関心を持ってもらえるよう概要を書く

あなたはTwitterのTLに流れてきたリンクを、ひとつひとつ丁寧にクリックしますか？
おそらくしないでしょう。

「おっ？これは面白そうかも」と関心のあるリンクをクリックするものです。

したがって、ちゃんと関心を持ってもらえるよう、記事の概要や狙う効果をツイートの文面に記述しましょう。

注意点

書き手が書きたいことをアウトプットするのが一番大切です。
本記事のノウハウに則ることが至上命題になって、アウトプットしたい内容が阻害されるのは本末転倒です。

また、Qiitaで探していただければ分かるかと思いますが、良記事は必ずしも本記事で取り上げたような構成にはなっていません。
別の論理展開で読みやすく書かれているのであって、本記事はノウハウの一形態に過ぎません。

その点に注意して参考にしていただければと思います。

以上、ここまでが本記事でお伝えしたいことです。
ここから先は余談です。

---

余談

特許明細書と同じフォーマットなんだよ

種明かしです。

この記事で紹介した基本構成。
実は発明特許の申請に用いる、特許明細書とほぼ同じフォーマットなのです。
特許明細書は以下のようなフォーマットになっています。

• 発明の概要
• 背景
• 発明が解決しようとする課題
• 課題の解決手段（技術、手法の構成）
• 発明の効果
• 発明の実施形態（発明の具体的な構成例）

技術を説明する論理展開において、特許明細書は非常に有効な構成であり、応用できるものだと考えます。

質の高い記事と技術力向上

人に伝わるように文章を書くには、考えを整理して言語化する必要があります。
しかしなんのサポートもなく、一朝一夕にできるものではありません。
本記事で取り上げた基本構成は、考えの整理と言語化を手助けするフレームワークです。

そしてそれは、記事の質を高めることにもつながると考えます。
考えの整理と言語化は、自身の技術の棚卸しなので、記事を書くことが技術力アップにもつながります。

ところで技術記事に関して、ネット上では「低レベルなゴミ記事を書くな」「検索のノイズになる」といった意見がたびたび見受けられます。

深堀りが不十分で、質が良くない記事は確かにあるでしょう。
しかし執筆した方々は、ワザと質の良くない記事を書こうとしたのでしょうか？
私は違うと考えます。

経済産業省によると、2030年にはIT人材が約79万人も不足すると言われています。
エンジニアの育成が急務とされています。

「ゴミ記事を書くな」と牽制するのは、エンジニアを萎縮させ、心理的安全性を阻害し、技術育成の妨げになるのではと、懸念を覚えます。

冷たくあしらい切って捨てるのは簡単です。
それよりも、質の高い記事を書けるよういざなう方が、全体的な技術力向上につながり、皆がハッピーになれると私は考えます。