技術系のネタを「ゴミ記事」にしないために注意すべき具体的なポイント

前回、「現実的、金銭的な収益を目指して技術記事をアウトプットするようにしたら、より読者のことを考えるようになるからアウトプットの質も上がってゴミ記事は減るんじゃね？」ってなことを書いた。

今回はそれとは別に、僕が良記事だと思うポイント、ゴミ記事にしないためのポイントを挙げてみる。

それぞれの事柄に関しては過去にこのブログで愚痴混じりの長ったらしい文章を書いているので、理由や根拠、メリデメの話はほとんどしない。

目次

• 良記事にするためのポイント
• 良記事と思われる要素
• ゴミ記事の特徴
• ゴミ記事を書いてしまう人の心理

良記事にするためのポイント

• 一つの記事は一つの話題だけ扱う
  • 過去に書いた記事へのリンクで、詳細な説明を省けたりする
  • 複数の内容をまとめて何か説明したければ、別途「記事のまとめ記事」を作る
• タイトルだけで何が書いてあるか推測できるようにする
• 見出しを適切に分け、見出しだけでどんな内容が書いてあるか推測できるようにする
• 執筆時点の作業環境、利用ライブラリのバージョン情報を記す
• 事象は読者が再現できるよう、手順と結果を正確に記す
  • コマンドとエラーメッセージはコピペで残す
  • メニュー項目の文言に至るまで一言一句正確に書く
  • 説明が下手な人は画面キャプチャを貼る
• サンプルコードは実行可能なコード全体を残すと良い
  • 記事の最後にでも「今回の内容を全てまとめたコード」を置いておくと再現・検証しやすい
  • CodePen のようなサンプルコードが動作するサービスを利用したり、Gist に置いたりすると良い
• 調べたことをダラダラ書く前に先に結論だけ書く
• 調べたこと、試してみて上手く行かなかったことなどは、参考文献 (URL) と参考にした箇所の引用とともに記す
  • 参考サイトの閉鎖・更新による文献消失を見越して引用もしておくと良い
• 根拠が説明できない対処法を書かない
  • 「なぜか分からないけどこのおまじないを書くと直る」みたいな記事は嘘を拡散する恐れもあるので注意
  • 自分で根拠が理解できていない、説明できない状態なら、もっと調べて説明できるようになるまで記事を書かないか、「調査中」とか「詳しい原因は不明」などと断り書きを入れておく
• 読み手がページ内検索したくなりそうな単語を想像して散りばめておく
  • エラーメッセージ
  • 略語と正式名称
  • 「URL と URI」のような類語、関連する語句
  • 「原因」「結論」といった単語
• 事実と所感 (個人的な思い) は分けて書く
  • ハマったポイント、理解に時間がかかったこと、今後気を付けたい点などは、調査結果や原因説明など「事実」を扱う章とは分けておく
• 体言止め、婉曲表現は避ける
  • プログラムは 1 か 0。ハッキリしない言葉遣いは徹底的に削る
• 定性的な表現ではなく定量的な表現をする
  • 「設定ファイルの下の方…」ではなく「設定ファイルの151行目」というように
• その記事を読む読者が必要としていなさそうな情報、何も説明していない文言は書かない
  • 「なんかエラーが出た」「上手くいかない」「何も表示されない」
    → 事象の説明として情報が不足しているし、期待値との相違が分からない。
    → 期待する動作はどうであり、それに対してどういう結果が出ているのかを書く。エラーメッセージが出ていればコピペする

良記事と思われる要素

何箇所か強調を入れたが、良記事に見られる大切な要素は、以下のようなものだ。

• 再現性 : 読者がその記事を読んだだけで、同じ状態・事象が再現できるかどうか
• 検証可能性 (証明可能性) : その情報が正しいかどうか、読者が確かめられるかどうか
• 客観的事実 : 主観が混ざっていないこと (分けて論じられていること)
• 根拠 : そのやり方で良い理由、他の手法ではダメな理由、どうしてその問題が起こったのか、など

ゴミ記事の特徴

これらを反転させてみれば、ゴミ記事の特徴、すなわち真似すべきでない、誰からも求められていない、役に立たない文章の特徴が分かる。

• 再現性がない : その記事で触れている事象が正確に分からない、どういう状態になっていて、それをどうしたいのか分からない
• 検証できない : 「暗黙の了解」や「前提とする知識」が読み取れず、説明が不足していることでそれが確かな情報か確認できない
  • 例えば、「Linux でエラーが起きたが、◯◯を入れたら直った」という文章は、Linux OS のディストリビューションも分からなければ、「◯◯を入れる」が示している具体的な操作も分からないので (ダウンロードするだけ？何かインストールコマンドを打つ？)、読者が同じ操作を行って検証できない
• 事実が分からない・主観と混ざっている : 「自分はこう思うから」が暗黙の前提になっていて、突然「こうするべきだ」などと書かれていても、読者は納得できない
• 根拠となる文献が分からない : どうしてその手法・対策に辿り着いたのか、どうしてそうすると上手くいくのか、などの説明や、参照した文献に関する情報がないと、正しいことを書いているのか分からない (読者がそれぞれ調べる手間が増える)

ゴミ記事を書いてしまう人の心理

このような文章を書いてしまう人は、まず「自分がどうしてその文章を書くのか」から考え直した方が良いと思う。文章を書きたくない、書くのは面倒だ、と思っているなら、無理せず書くのを止めた方が良い。そのような状態では、いくら書いても何も成長しない。何か指示らしきものをもらって、ただ「書かされている」状態の人が、こういうゴミ記事を発信しがちだ。

文章を書くことで自分がどうなりたい、とか、こういう人にこう思って欲しい、とかいう目的がハッキリしていないと、「自分はこうした」「自分はこう思った」という主観的な記事しか書けないだろう。読み手のことを考えていない以上は、個人的な走り書きのメモに等しい。あるフリーソフトの「インストール方法を解説する記事」と「自分がどうやってインストールしたかを説明する記事」は、全く違うのだ。言わずもがな、後者がゴミ記事になるメンタリティだ。「自分がどうやってインストールしたか」という実績から、「あなたはこうやってインストールすると良いですよ」とガイドする記事に変換する、手間をかける必要がある。

このような点に気を付けて、ゴミ記事を生み出さず、良記事を発信できるようにしてほしい。