Zenn
レバテック開発部
🦁

年間700本ドキュメントを書く人間の技術ブログ執筆方法

もりた
2024/02/26に公開
アウトプット
idea

これはなに

ども、レバテック開発部のもりたです。家族全員風邪引いてます！！

2024年2月より、レバテック開発部でもZennの運用を始めました。もりたはこういう記事を書くのが大好きで、社内のドキュメント共有システムに年間700本くらいの資料やメモ書きを残しています。たぶん記事を書くのは得意な方の人間だと思うので、どうやってアウトプットを作るのか？　という点についてこれを機にまとめてみました。

具体的に扱うのは、どうやって書くことを見つけて、どのように書くのか？　という点です。

構成

  • 以下の点について書きます。
    • ネタ出し未満
    • 企画
    • 実際の書き方
  • 書かないのは以下の点です
    • アウトプットのメリット
    • DevRelと技術記事
    • 上手な文章の書き方

1. ネタ出し未満

ここでは、記事を書く前に、まず日常的にやっておくといいぞ、みたいなことを紹介します。記事っていきなりできるんじゃなくて、揺籃期みたいなのが必要です。具体的になにが記事を生み出すのかというと、メモを書くことです。

1-1. メモを書こう

技術記事をどうかくか？　ということを考える際、ほとんどの場合は「ネタをどうやって記事にするか？」という視点で語られることが多いと思います。ただ、記事が書けないよという人はまずそのネタが思いつかないのではないでしょうか？

実際、なにもないところから技術記事を書くためのネタをいきなり考えるのってそれなりにハードルが高くて、よく発信できている組織やメディアほど、発信未満の発信を行う仕組みがある印象です。

例えば以下のような例があります。

SF作家のセオドア・スタージョンも「すべてのものの90%はカス」みたいなことを言っていますが、これは良質なアウトプットの背景にはたくさんの気軽なアウトプットがあるということを示しています。全ての打席でホームランを打つことはどだい無理な話で、良い記事を書くためには低質なものを気軽に発表する基盤が必要になります。冴えた記事がたったひとつあっても意味がないのです。

1-2. どんなふうにメモを書くか？

メモの書き方は自由ですが、例えば仕事の中で自分の抱えた問題（実装がうまくいかないとか）を解決するまでの過程をメモしていくのは有用です。もし複数の情報源に当たらないと問題が解決できなかった場合、そのメモがそのまま技術記事になりえます。

また、自分が日頃感じている気持ちを書いていくのもおすすめです。例えば「XXという技術がわかってない」とかのフラストレーションを書いておくと、自分はその技術が気になっているんだなという自己認識につながり、勉強するきっかけになります。学んだことはそのまま記事にすることができます。

また、以下のような事例もあります。参考にしてみてください。

数年間継続している「作業メモ」の話 - zenn

2. 企画

次は企画のやり方です。具体的には、ネタが出たところから、これは書けるなとなるところまでを整理します。

2-1. ネタは無理して出さなくてOK

はじめに、無理してネタを出す必要はありません。メモ書きのところでも書いてますが、メモを書いていると割とネタは出てきます。なのでそれを書けばいいです。思いつかないならメモを書きましょう。

それでも出したい人はコンテンツ制作やWebマーケティング周りの書籍を読むとネタ出しの方法は無限に書いてあるので、そういう方面で調べごとをしてみると良いです。また、知りたいことだけあって調査して記事を書くというのも楽しいんですが、今回はそのやり方は割愛します。（なおこの記事はちょっと調査して書いた、先日投稿したデータベースおすすめ本17選の記事も調査して書いた）

2-2. パンチラインを考える

ネタが出たら、パンチラインを考えましょう。パンチラインとはその記事の面白いところ、価値の中心がどこにあるのか？　という話です。

これを考えると良いのはパンチラインがあったほうがバズるから、ということではありません。どこが面白いのか明確になっていると記事を書き切ることが簡単になるし、記事執筆の指針になるからです。

2-3. ネタには種類と提供価値がある

パンチラインを考えるにあたって、ネタの種類とか提供する価値を意識するとやりやすくなります。以下にいくつかの例を示します。

  • ネタの種類
    • エラーの解消、How-To、ツールの紹介、概念を解説する、ベストプラクティス、書評、作ってみた系記事
    • 他にも色々
  • 提供する価値
    • 届ける価値
      • 知らない情報やまとまっていない情報を届ける
      • ツールの紹介や書評、まとめ記事など
    • 読まれる価値
      • 読んでいて単に面白い記事
      • 概念を伝えるもの、ベストプラクティス、作ってみた系
    • やってみる価値
      • 検証してみて価値を伝える
      • エラーの解消、How-To、機能の紹介

たとえば使っているライブラリのアップデートがあり、新しい機能が追加されたとしましょう。その機能を紹介する場合、記事の中心は検証の価値です。そうなるとどんな環境で、どんなコードを書いたときにどんな動きになったのかというのができるだけ再現性のある形で示されていると読者は嬉しいです。

このように、この記事がどんな種類でどんな価値を届けるものなのかを考えると、パンチラインが整いやすくなり、どんな内容を書けばいいのか？　というのも定まってきます。

ここらへんもコンテンツ制作系の書籍を買うと書いてあるような気がします（インプレス社のいちばんやさしい〜〜の教本シリーズにいい感じのがあったような気がするけど、タイトル忘れました）。

3. 実際の書き方

もりたはこうやって書く、というのを紹介します。（若干こじつけっぽいですが、）テスト駆動開発ライクな書き方をすると良いです。具体的には

  • この記事はなんなのか？　をまず書く
  • 章立てを考える（Red）
  • 章立てをもとに内容をざっと書く（Green）
  • 校正する（Refactor）

ってかんじ。まずなにを書きたいのかを決め、小さな項目にわけ、それぞれを読める状態にしていき、最後により良い状態にブラッシュアップします。
（なおt-wadaさんのTDD Boot Camp 2020 Online 基調講演で語られていたTDDの手順はこちら）

3-1. この記事はなんなのか？　を書く

もりたの書く記事には基本的に「これはなに」という章があります。これはその記事でどんなことが分かるのかというのを示したもので、その記事のゴールになります。

ゴールが示されていると読者が読みやすいというのもあるんですが、基本的には記事の扱う範囲を定めるためにやっています。企画が甘いとこれを書いた瞬間に「ゴールが遠すぎる」「おもんないな」となるので、そういうときは下書きに眠らせることになります。RIP

3-2. 章立てを考える

具体的に扱う内容を定めていきます。パンチラインとの乖離が起きないように進めます。ただ、もし乖離したら乖離したでよくて、書きたい内容とずれているなと思ってパンチラインを練り直します。

また、できる限り、章単位でも面白いところを詰めていくと良いです。まあできたら。

ちなみにこの記事の当初の章立てはこんなかんじでした。

- これはなに
    - Zennでの活動が公式に始まって技術記事を書く機会が増えてきた
    - 正直もりたはこういうの得意なので、どうやってアウトプットをするのか？　というのを一回整理して共有した方がいろいろといいかもなと思った
    - 構成はこんな感じ
        - アウトプットの隠れたフェーズ
        - ネタ出し
        - 実際の書き方
        - 公開とその後
- アウトプットの隠れたフェーズ
    - いきなりは思いつかない、記事未満のメモを作る
    - クラスメソッドもゆめみも、Zennもそういうモデルでやっている
    - 書くためにインプットする、インプットするために書く、喋る、飲み会に行く
- 思いつきを書けるかもまでつなぐ企画
    - パンチラインを考える
        - 自分の体験とか課題がすでにあるやつ
    - パンチラインを考えない
        - 総論的な書き方をしたいやつ、自分の中で色々調査したいやつ
        - そのあとにまとまりのよい単位で切り取る
- 実際の書き方
    - 書きたいことの列挙、箇条書きで構成、肉付けして枝葉を落としておわり
- 公開とその後
    - （おれはここ興味ないんだけど）フィードバックとか

（だいぶずれてるけどまあそんなもんです）

3-3. ざっと書く

章立てをもとにざっと書いていきます。
最初はだいたい箇条書きで書き、箇条書きで書けたら箇条書きを崩しながら文章にしていきます。

3-4. 整形・校正する

ここまでで文章は一旦かけています。そこまでできたら、画像やリンクなどの情報を付け足したり、文章の校正をしていきます。

また、できれば校正をする際は一週間くらい記事を寝かせた上でやると良いです。書いた直後は記事と自分が近すぎて、どこがわかりにくいか？　文章としておかしくないか？　が把握できません。一ヶ月前に自分の書いたコードが読めなくなる現象を逆に利用することで、校正はやりやすくなります。

おわりに

というわけでもりたによる技術記事の書き方でした。

この記事を通して伝えたかったのは、書くことって楽しいから、みなさんもぜひ書いてみてくださいねということです。すごい記事を書かなきゃと思う人もいると思うんですが、どんな小さな記事でもそれがあることで別の何かを生み出すきっかけになったりします。いまひとつ踏み出せずにいる誰かの背中を押せる記事になっていれば幸いです。

アンケート

技術ブログを書くにあたって、どんなことがハードルになる・不安に思うのかのアンケート（3分くらい）を作成しました。よければ回答してください。
https://forms.gle/boRjLABgQxmo1EGM7

参考にした記事・スライド

レバテック開発部
レバテック開発部

レバテック開発部の公式テックブログです！

Discussion