なかなかアウトプットできないあなたが技術記事を書くときのコツ
技術記事を書くまでのステップについて順にコツを解説していきます。
特に、技術記事を書きたくてもテーマ選定が難しい、文章が苦手だ、なぜか筆が進まない、うまくまとめられないといった方に読んで欲しい記事です。
一応、エンジニア歴としては数年以内のジュニアレベルの方を想定しています。
以下のように技術記事を企画して、書いて、公開するためのプロセスごとにちょっとしたコツをまとめています。気になるセクションだけでも読んでいただければ幸いです。
- テーマを決めよう
- 対象読者を決めよう
- 章立てを決めよう
- 書こう
- タイトルを決めよう
- 【余談】技術記事を書く理由とは
筆者について
- QiitaとZennにて6年以上の記事発信経験があり、
- Qiitaでは5,942Contributionsを記録、
- Zennでは3,253Likesをいただいています。
テーマを決めよう
コツ：テーマのカテゴリによって執筆のポイントや難易度が変わってくる。最初は難易度の低いテーマを選ぶのが吉
技術記事は何種類かに大別される
技術記事といっても何種類かに大別されており、それぞれ書くときのポイントや求められる技術力が異なっていると思います。まずはそのあたりについてざっくりまとめてみました。
- なんらかのツール、ライブラリの紹介
- 言語やフレームワークのベストプラクティス
- 概念を教えるタイプの記事
- 特定のコンテキストにおけるちょっとしたTipsや問題解決事例の紹介
- 開発チームで生産性を上げたり、問題を解決したり、前に進むためのTips系
- その他
- 単なる備忘録（Zennのスクラップなど）
- お気持ち表明したポエム
いまパッとZennのTrendを開いてみたところ、上記のように大きく5つの種類に分かれるように感じました。
それぞれのテーマごとに、提供価値や記事のポイントが異なります。
なんらかのツール、ライブラリの紹介
提供価値：そんなツールやライブラリがあるんだ！とそもそも知ってもらうこと。または既知のツールでもあまり知られていない設定オプションなどが紹介される
記事のポイント：紹介する内容によってどのような改善が得られるかが明確なこと。この記事を読んだ人がどんな改善ができるのか。ツールやライブラリの内容は幅広いのでスコープを狭めることもPoint
執筆難易度：低め
人気度：中
言語やフレームワークのベストプラクティス
提供価値：ある程度当該言語やフレームワークに精通している人が、断片的な知識や経験を統合でき、よりクオリティ（保守性など）が高いプロダクトを開発できるようになること
記事のポイント：紹介する内容の妥当性を示せること。妥当性とは前提条件と精度の掛け合わせによって生まれるので、技術的に間違いがないことはもちろん、どういった前提条件下におけるベストプラクティスなのかを明示または読むとわかるようにする
執筆難易度：高め
人気度：高
概念を教えるタイプの記事
提供価値：抽象化した概念を読者に提示することで、今後当該分野の知識を得たときの理解速度や、アウトプットの精度が高められるようにする
記事のポイント：教えたい技術領域について、まず自身が実際に手を動かしたりプロダクト化するところまで進めた経験があること。また、対象読者の選定が特に重要。相手の前提知識レベルを言語化できていないと説明が難しい
執筆難易度：高め
人気度：中
特定のコンテキストにおけるちょっとしたTipsや問題解決事例の紹介
提供価値：大半の記事はバズるタイプの記事ではなく、該当のコンテキストに遭遇した人が見かけて読む記事です。必要に迫られたときにGoogle検索でサッと見つかってサッと問題解決できることが提供価値となります
記事のポイント：コンテキスト自体の説明はある程度省いてよく、Tipsだけを端的に示す方が読み手にとって優しいことが多い
執筆難易度：低め
人気度：低
開発チームで生産性を上げたり、問題を解決したり、前に進むためのTips系
提供価値：開発チームの運営に関わっているマネージャー層等に参考になる情報を提供できること
記事のポイント：最終的にこういう制度を作りました、だけでなく具体的なTipsや、制度を作るための過程などの生々しいエピソードがウケることも多い
執筆難易度：中※ただし書くためにチームの運営に関わる必要がある
人気度：中
あなたが最近関わったプロジェクトや個人で検証した内容、読んだ書籍などから、上記のカテゴリに該当しそうなテーマをそれぞれ洗い出してみましょう。意外と自分では自分がたいした実績を出せていないと思っているだけというケースもありますので、周囲の人に自分が書けそうなネタが無いか聞いてみるのもいいでしょう。
おすすめは執筆難易度を低めに設定しているテーマです。結論を検証しやすく自信を持って書きやすいテーマだと思います。
どうしてもテーマが決められないときの処方箋
カテゴリをざっと見ても、自分が書きたい、書けるテーマが見つからないという方に処方箋的な考え方を示します。
テーマが見つからない方は有益な記事が書ける自信がなかったり、逆に間違った内容を書いてしまうことを懸念していることが多いと思います。
この考え方に向き合うためのTipsをいくつか書いておきます。
まず、有益な記事かどうかについてですが、たとえば 「この知識を知る前の自分には少なくとも役に立つ。同じくらいの知識レベルの方が世界に絶対1人はいるはずだ」などと考えるのがいいと思います。極端な話、それを知る/理解する前の過去の自分に向けて書けばいいのです。
また、有益かどうかというより、独自性のある情報かどうかという軸で記事を書くのも有りです。たとえばライブラリのちょっとした機能を使ってみた、という記事を書きたいとして、すでに巷にそういう記事があるから書いても意味が無いのではと思っているとします。こういうときは、「自分が開発しているサービスではこういう課題があって、この機能を使ってこういう嬉しいことが有りました」という”事例”や”背景”を載せることで、独自性のある記事になります（し、ライブラリの作者さんが見たらすごく嬉しいでしょう）。
次に、間違った内容を書いてしまうという懸念についてですが、以下のことを心がけていれば問題ないかなと考えています。
- 「こういう条件下で、こういう実装をしたら、こういう結果が得られました」というように、事前条件とやったことと結果を分けて漏れなく示すことが望ましい
- 逆に言えば、これらのいずれかに自信がない場合は記事中で自信がないことを明記しておくと安全です
- 根拠・前提条件が薄い状態でフレームワークやライブラリ、言語をDisらない
- 公式ドキュメント等へのリファレンスを貼る
- 自信が無いところは、同僚や知人のエンジニアにも見てもらう
あと、僕自身がよくやっていることなのですが、日頃から記事で書きたいテーマを思いついたら「とりあえずToDoリストに入れておく」または「とりあえずZennのGitHubリポジトリでタイトルだけ適当につけた空markdownファイルを作っておく」のがおすすめです。
そして、休日等に気が向いたときに書き進めればいいのです。
対象読者を決めよう
コツ：記事を書くのに慣れていないうちは、読者のレベルを思い切り高くするのが良いかも
対象読者の選定は非常に重要です。
対象読者について考えるべきことは
- 対象のテーマについて、どこまで知っていて、どこから知らないのか
- 単語レベルで、何を知っていて何を知らないのか
- 対象読者は、何について知ることができれば必要十分なのか
あたりが考えられていれば、一旦OKです。
たとえば、React Nativeアプリケーションを作る際のフレームワークにExpoがありますが、このExpoの特定のバージョンにおける特定の機能の説明をする記事なのに、いきなり「Expoとは」の説明から入っても無意味です。特定の機能について知りたい時点でExpo自体については知っているはずだからです。
というように、記事を書くのに慣れていない間は、対象読者が知っていることを多めに捉えておくことで、書くハードル自体は下がるかもしれません。
また、記事を書き始めるときに対象読者について考えておくのも重要ですが、書き始めてからも対象読者に思いを馳せるのは非常に重要です。たとえば個人開発で利用しているライブラリについての解説を書こうとしたとき、ライブラリのサンプルコードにうっかり個人開発のサービスを知っていることを前提にした実装を書いてしまったら、読み手が混乱します。
他にもサンプルコードに全然関係ないライブラリのコードが混在しているなどもたまに見かけます。「対象読者は、何について知ることができれば必要十分なのか」をチェックしながら記事を書き進めましょう。
章立てを決めよう
コツ：箇条書きでもいいから、どの順で何を話していくのかあらかじめ考えておこう
簡単にツールの紹介だけして終わるような記事を除いて、大半の記事では章立てが必要です。
本文を書き始める前に簡単な箇条書きで良いので、章立てを考えましょう。
前章で決めた対象読者の知識レベルを元に、何を解説していけば最終的に読者は納得するか、成長するかというのを考えます。
章立てを決める際は章の数が増えすぎないようにしましょう。慣れないうちにあまりたくさんの章がある記事を書き始めると普通に心が途中で折れるので、たとえば6つ以上章がありそうなら読者のレベルや、記事のゴールを再考するといった感じで調整してもいいかもしれません。
たとえば、ESLintのstrict-dependenciesプラグインを自社プロダクトに導入してみた事例を発信したいと思った場合について考えてみましょう。
以下のように章立てを考えていると、相当多くを語らないといけないように見えますね。
- ESLintとは？
- ESLintの代表的なルール
- ESLintのプラグインとは？
- ESLintの代表的なプラグイン
- strict-dependenciesプラグインが解決する課題
- strict-dependenciesプラグインの機能
- strict-dependenciesの自社における設定例
- 今後活用したいこと
しかし、本記事の目的はあくまで「自社プロダクトに導入してみた事例」なので、以下の章だけで十分なのです。
- strict-dependenciesプラグインが解決する課題
- strict-dependenciesの自社における設定例
- 今後活用したいこと
これはわかりやすすぎる例ですが、言いたいことだけを最低限言うというのを心がけると書くハードルも下がるのではないかな、と思います。
章立てを決めておくと、書き始めてから進捗管理の目安にもなるので便利です。全部で4章あって、1章書き終わって30分経っていたら、全体で2時間以上掛かることを見立てられます。
書こう
コツ：とにかく結論ファーストで各章、各段落を書く！
文章を書くときは、各段落を原則結論ファーストで書くようにしましょう。
（自分も完璧にできているわけではないので偉そうに言えないのですが）
結論ファーストと言われても、具体的にできている例とできていない例を挙げないと難しいと思うので、本記事内から例を出してみます。
▼結論ファーストな文章の例
章立てを決めておくと、書き始めてから進捗管理の目安にもなるので便利です。全部で4章あって、1章書き終わって30分経っていたら、全体で2時間以上掛かることを見立てられます。
▼結論ファーストではない文章の例
全部で4章あって、今1章で30分経っていたら、全体で2時間以上掛かることを見立てられます。なので、章立てを決めておくと、書き始めてから進捗管理の目安にもなるので便利です。
どうでしょうか。結論ファーストな文章では、一文目で何が言いたいのか分かるので、後半の文章もその具体例ということでスムーズに入ってきます。一方、結論ファーストではない文章では、いきなり何を言われているかさっぱりわかりませんね。後半を読んでようやく、今のが具体例だったのかということがわかります。
結論ファーストで文章を書くのは読み手にも優しいですし、慣れると書き手にも優しいです。具体例による補足や裏付けは最悪なくても記事として成立しているので、まずは結論をサクサクと書いてから、仕上げとして補足を書く選択肢が生まれます。
まずはこの記事でもいいですし、Zenn等で人気の記事でもいいので、この原則が守られているか調べてみるのもいいでしょう。そうすることで、ただの文章の羅列だった記事が「結論」と「それを支える根拠」に分かれて見えてきます。その段階にいくと、自ずと自分の文章も改善されてくるというわけです。
結論ファーストな文章を書くとよいのは以下の書籍の受け売りです。ぜひ読んでみて下さい。
ちなみに本記事において、各章の出だしに「コツ：XXX」と書いてあるのもこの考えの応用です。先に結論を見せることで、読者にその後の文章をその結論の裏付けであると意識させながら読んでもらえます。
文字数について
章立てを決めたり実際に書き進める際に意識することになる文字数ですが、文字数が多いから素晴らしい記事だとか、少ないから大したことない記事だとかそういうことはありませんので、気にせず書いてもらえればと思います。
むしろ、私は文字数を書きすぎてしまうくせがあり、ついつい本記事のように物量がありすぎる記事を書いてしまうので公開前に少しでも削る作業に時間を食われてしまいます・・・
その他、読みやすい文章を書くための一般的なコツ
- 形容詞や副詞は黄信号
- たとえば「大きな」とか「とても」、「けっこう」などの形容詞や副詞が文中に登場したら黄信号です
- 「こういう改善をしたらフロントエンドのパフォーマンスがとても良くなりました」などと記事に書いてあったら、「一体どの尺度でパフォーマンスが良くなったと言えるんだろう？」と疑問に思いますよね。こういった場合はLighthouseのスコアを載せるなど、何の尺度で改善したのか、具体的な数値ベースで語るのがよいです
- 言い切る
- ケースバイケースではありますが、記事の重要な論点になる場面で語尾が「〜かも」となっていたり、「たぶん」が入っていると読み手が不安になります
- 書き手自身が、自信を持って発表できるようにエビデンスを揃えたり、スコープを絞るなど工夫しましょう
- 注釈は後に書く
- 文章を書いているとついついカッコ書きで補足を入れたくなりますが、いちいち入れていると結論が遠のいて読むのが大変になります。注釈はこちらの機能を使うなどして段落の後に飛ばしましょう
タイトルを決めよう
コツ：タイトルは「キャッチー路線」VS「SEO対策路線」！ですが、最初は難しく考えずに「○○を○○した話」形式がいいかも。
まずはタイトルを考えるタイミングですが、タイトルは記事を書き終わった後に考えるのが良いと思います。記事を書く前に考えたタイトルは十中八九書き直すことになるからです。
記事を書き終わった直後は、「書き終わったぞ！」という高揚感に少なからず浸っているかと思います。そのテンション感でタイトルを勢いよく考えましょう。
個人的にはタイトルは主に3パターンに大別されると考えています。
- 「（○○な状況下で）○○を○○した話」パターン
- 例：「稼働中のLaravelアプリケーションにSentryを導入した話」
- 例：「【JavaScript】アロー関数式を学ぶついでにthisも復習する話」
- もっとも考えやすいタイトルだと思います。目的語と動詞を考えるだけでよいからです
- 「キャッチー路線」パターン
- 例：「そのuseState、もっと減らせるかも？コンポーネントの事例と一緒に示します」
- 例：「PhpStormを使ってるのに、わざわざ未だにブラウザでDeepL翻訳してるってマジ？」
- タイトルを見て、思わず「読んでみよう」と思わせる文言を使っています
- 読者はその瞬間は記事を読む必要がない状況でも、とりあえず読んでおこうと思ってもらえるようなタイトルにする必要があります
- 「SEO対策路線」パターン
- 例：「FirestoreのセキュリティルールおよびCloud Functionsのテスト実装方法と自動化」
- 上記の例だと「firestore テスト自動化」等でググったときに上位に出ることを狙っています
- タイトル内に、この記事を求める人はどんなワードでググるのかを考えたときに必要そうな単語を確実に含めます（順位はともかくCTRが上がると思います）
ただ、一応分類はしましたが、そもそも記事のテーマがどういったカテゴリなのかによってタイトルの路線が決まりそうです。
たとえばライブラリの解説や特定のコンテキストにおける問題解決の記事は、必然的にその内容を端的に示すタイトルになるので、「○○を○○した話」パターンまたは「SEO対策路線」パターンにすることが自然です。
しかし、ベストプラクティスの解説をする記事や概念を説明する記事の場合、読み手は今すぐその情報を求めていなかったり、Google検索で見つけられる可能性が比較的低いので、タイトルをキャッチーにしてトレンド入りを狙うほうがより多くの人に見てもらいやすいような印象があります（もちろん内容が伴っていることと自身の発信力があることが前提です）。
というわけでこれまでの話を統合すると、頑張ってこれから技術記事をアウトプットしていこう！という方が付けるタイトルは「○○を○○した話」パターンが無難だと思います。
【余談】技術記事を書く理由とは
さて、ここまでの流れで記事が書けて、タイトルも付けられていると思います。なのであとはZennなりQiitaなりお好きなプラットフォームで公開していただければと思いますが、最後に技術記事を書く理由、メリットはそもそも何なのか？という問いに対して私なりの答えを述べておこうと思います。
技術記事を書く理由として一般的に考えられるものを挙げてみます。
- 自分のための備忘録として
- 将来の自分のために理解したことをまとめる
- みんなにライブラリを宣伝したい
- 所属している会社を宣伝したい
- 個人開発しているサービスやOSSを宣伝したい
- バズりたい
- 転職活動に活かしたい
色々ありますが、個人的におすすめな目的は「自分の学びを深める」です。
自分が学んだことをそれを知らない誰かに対して発信する、文字や図表を用いてまとめるという行動を通して理解を深めることができます。
一般的に学習のプロセスは「内化」と「外化」を繰り返して行われるとされています。
内化は読んだり聞いたりすることを通して知識を習得すること、外化は書いたり話すことを通して”理解”や”思考”を表現することです。
外化のプロセスを経ることで、自分がハッキリとは理解していなかったことを知ることができます。いわゆる「無知の知」というやつです。
ESLintのプラグインの設定例を解説する記事を例に挙げます。記事を書く前は、自社プロダクトに導入した設定例を紹介するだけだと考えていました。しかし書き始めると、「自分が書いた設定方法以外の書き方はあるのか？」「設定が反映した結果は世の中的に正しいと言えるのだろうか？」「違うプラグインで同等のことができないのか？」「バージョンは最新のを使っていたっけ？」「うちはReactだけどVue等でも通用するのかな。通用しないなら前提条件に書かないと！」など色々な疑問が湧いてくるでしょう。それが「無知の知」です。
そういった疑問を全部解消してから記事を公開するのも、わからないところを正直にわからないと表明して記事を書くのも自由です。大事なのは、書くというプロセスを通して、自分の理解が足りなかったところを知ることです。
目的が自分の理解を深めることに向いていれば、思ったよりLikeがつかなかったときに凹むこともないのでおすすめです笑
（ちなみに私が本記事を書いている理由は、会社の同僚にもっと技術記事を書いてみてほしいからです）
ぜひ、ご自身が決めたテーマについて記事を書いてみることで、理解を深めていきましょう。
最後まで読んでいただきありがとうございました！記事が参考になったらバッジお願いします！
Discussion
素晴らしい記事をありがとうございます！
とても共感します！ADR とか、ファインマンテクニックに通じるところがあると思います。
対象読者を的確に設定するのも (少なくとも自分には) 難しい行為だと思います、なので
この四行はとても示唆に富んでいると思いました。
很久没见到如此纯粹专门面向工程师氛围的社区了，许多文章看起来干货也很多。
对于开发者而言，basic theory和 practice 对解决实际需求和掌握技术无疑是最重要的。
加油，持续学习 持续输出对于自身修行 内心世界是积极的。
コメントありがとうございます！翻訳しました。