はじめに
昨日、こちらの記事を拝見しました。
良い記事を書くためのガイドライン - Qiita:Support
上の記事は「あなたの知識が他の誰かの役に立つようにするため」のQiita公式のガイドラインです。
これを読んでると「うんうん、なるほど。そうだよねー」と思うところばかりでした。
それにかこつけて、僕もどういうことを考えながらブログやQiita記事を書いているのかを紹介してみようと思います。
個人的な良い記事のガイドライン = 2ヶ月前の自分が泣いて喜ぶような記事を書く
何を考えながら書いているのかというと、この記事のタイトルにある通りです。
まあ「2ヶ月前」っていうのは適当で、「昨日」でもいいし、「2年前」でもかまいません。
要するに「2ヶ月前の自分」＝「その知識を知らなかった頃の自分」ということです。
技術記事を書くときは、自分の書いた記事を過去の自分に見せたときに、
「あー、なるほど！最初っからそう説明してくれたらすぐわかったのに！！」
と大喜びしそうな内容を書こうと心がけています。
世の中には「2ヶ月前の自分」がたくさんいます。
そういう人たちはネットを検索したりしてあなたの記事にたどり着きます。
その記事の内容が「2ヶ月前のあなた」が喜ぶように書かれていれば、きっとその人たちもあなたの記事を読んで喜んでくれるはずです。
さらに、ストックがたくさん付いて、はてブもたくさん付いて、記事がバズって、一躍あなたも有名人！！・・・になれるかもしれません。
もう少し具体的に
過去の自分が喜びそうな記事とは、どんな記事でしょうか？
一般化するとこんな感じかなと思います。
- まず最初に伝えたい内容を明確にする
- タイトルや本文の「はじめに」で「この記事は何か」を伝えます
- 問題解決系の記事は問題、原因、解決策を明確に分ける
-
#や##を使って見出しを分けると良いです
-
- 知見共有系の記事は「過去の自分は何を知らなくて、今の自分は何をどう理解しているのか」を意識しながら記事を書く
- 自分がはまったり、勘違いして理解していた内容を「初心者によくある間違い」として共有するのも効果的
問題解決系の記事のサンプル
Pow + rbenvでlocalの.ruby-versionが無視される場合 - Qiita
この記事は典型的な問題解決系の記事です。
本文は以下のような構成になっています。
- 問題
- Powを再起動しても、なぜかRailsが以前のバージョンで動く場合がある
- 原因
- プロジェクトの上位ディレクトリに別の.ruby-versionがある
- 解決策
- 上位ディレクトリに不要な.ruby-versionがあった場合は削除する
- ライブラリのバージョン
- Pow 0.4.0
- 参考にしたwebページ
知見共有系の記事のサンプル
Ruby - Minitestで絶対誤差と相対誤差を利用したテストを実行する - Qiita
この記事を書いた動機はMinitestの assert_in_delta と assert_in_epsilon の違いがわからなかったためです。
いろいろ調べてようやく違いがわかったので、過去の自分と同じように違いがわからない人に向けてその違いを説明する記事を書こうと思いました。
この記事の構成は以下の通りです。
- はじめに
- この記事は二つのメソッドの違いを説明する記事である、と明言する
- assert_in_delta の説明
- メソッドの仕様を説明する
- 必要に応じてサンプルコードを使う
- assert_in_epsilon の説明
-
assert_in_deltaと同様にassert_in_epsilonを説明する -
assert_in_epsilonはassert_in_deltaよりも（僕は）理解しにくかったので、特に詳しく説明する
-
- まとめ
- 記事をしめくくる
- まだ十分で理解できていない点があることも伝える
一方、メモや備忘録の類いは「未来の自分」が喜ぶ記事
冒頭で紹介したQiitaのガイドラインの中には、あまり適切でないタイトルの例が載っています。
- 「Rubyメモ」
- 「正規表現でハマった」
- 「OpenSSLのバグ」
こういったタイトルの記事は中身を読んでも「自分のための備忘録」といった体で書かれていることが多いです。（全部が全部とは限りませんが）
もちろん、メモや備忘録であっても読んだ人の中には「ありがとう、助かった！」と思う人もいるでしょう。
なので、全く意味がないとは言いません。
ただ、メモや備忘録はたいてい「未来の自分」が喜ぶ記事になっています。
つまり、僕の考えるガイドラインとは逆方向を向いているわけです。
「未来の自分」はその記事の背景やコンテキストを理解しているので、大雑把な内容でも「あ、そうだった」と当時の状況をすぐ思い出すことができます。
しかし、第三者がその記事を読むと背景やコンテキストを共有できていないので、記事を書いた本人のようにぱっと内容を理解することができません。
「知見を共有しよう」という動機自体はとても素晴らしいことです。
ただ、具体的な説明もなしに「リンクやコードを数行載せて終わり」ではちょっともったいないです。
そうではなく、「過去の自分」が喜ぶように「おもてなし」を施すと、記事の価値が全然違ってきます。
というわけで、投稿ボタンを押す前に「この内容で過去の自分は喜ぶかな？」と自問自答してみることをオススメします。
僕の場合、メモや備忘録はKobitoに溜めていってます
Qiitaに公開するのは「過去の自分」が喜ぶ記事ですが、「未来の自分」が喜ぶメモや備忘録も僕はちゃんと残しています。
僕の場合、そういったメモはKobitoに残していってます。
僕のKobitoデータベースにはQiitaに公開した記事だけでなく、自分用のメモや備忘録もたくさん入っています。
例えばこんな感じです↓
人によっては「これでも公開しちゃえば？」と思う人もいるかもしれませんが、僕のガイドラインの中では過去の自分が喜ぶ記事になっていない（説明が不十分で理解するのにおそらく時間がかかる）ので、外部には公開していません。
「ストックしました」の通知は良い記事だったかどうかのバロメータ
Qiitaの場合、「記事がストックされた」＝「他の人に喜んでもらえた」と考えて良いと思います。
僕の場合、だいたい1日に10件以上「ストックしました」の通知が飛んできています。
通知一覧を開くとこんな感じです。
みなさんも「ストックしました」の通知を良い記事だったかどうかのバロメータにしてみると良いかもしれません。
まとめ
というわけで、この記事では僕が個人的に考える「良い記事のガイドライン」を紹介しました。
繰り返しになりますが、「過去の自分」はあなた一人だけではありません。
世の中には「過去の自分」と同じ人たちがたくさんいます。
その人たちは役立つ情報を求めてネットを検索し、あなたの記事にたどり着きます。
そしてもし、その記事の内容が「過去の自分」が喜ぶように書けていれば、きっとその人たちも同じように喜んでくれるはずです。
「情けは人のためならず」ではありませんが、他の人にとって役立つ記事を書いていれば、あなた自身の評価も上がり、就職したり転職したりするときの強力な武器になるかもしれません。
もしあなたが今まで無頓着にQiitaの投稿ボタンを押していたなら、今後はボタンを押す前に「過去の自分は喜ぶかな？」と自分自身に尋ねてみてください！
あわせて読みたい
あなたのブログに「WIIFY(ウィッフィー)」はありますか？ - アウトプットの価値は受け取る側のメリットで決まる、というお話 - give IT a try
その昔、この記事と同じような内容を自分のブログに書いたことがあります。
この記事に書いていない話もいくつか載っているので、よかったら読んでみてください。