【Qiita】今日からできる！見やすい記事の書き方

はじめに

「Qiitaはいいぞ」というのをRUNTEQの雑談会で話したのですが、それに付随して自分が意識していることをまとめていたら「これだけで記事にできるんじゃないか？」と思ったので、単体で記事として残しておくことにします。
記事を書くなら読み手のことをいろいろ考えなければならないのですが、とりあえずこれだけ気をつけておけばいいんじゃないかなという内容を取り上げました。
せっかくなので、記事タイトルは煽り気味に付けさせていただきました。今日からできます。

この記事の対象者

Qiitaで記事を書いたことがない。
どんなことを意識して記事を書いたらいいのだろう？
初めて記事を書いてみたものの、なんか見づらい気がする。

意識すること

タイトルのわかりやすさ

タイトルは記事の顔です。
シンプルな言葉で何についての記事かわかるようにしましょう。
私は基本的には下記のように書いています。フォーマットをある程度パターン化するとタイトルを付けやすいのでおすすめです。

【Rails】enum_helpを用いてi18n対応セレクトボックスを作成
【Rails】一対一対多のアソシエーション
【MySQL】Mysql2::Error::ConnectionError　自分用メモ
【Rails】SorceryでTwitter認証
【SSH】公開鍵認証とEC2について
【AWS】インスタンスもボリュームもないのに課金される謎が解けた
【Rails】入力された値を元にGETリクエストを送ってjsonを取得し、DBに保存する

このような書き方でなくとも、技術の名前をタイトルに書いていない記事はほとんどないと思います。
ちなみに、「自分用メモ」というのは、記事として体裁が成っていないので期待しないでねという意味を込めて付けています……。

見出しの構成

見出しも重要です。
内容が短いなら無くてもいいと思いますが、ある程度構成のある長い記事なら必ず付けてください。この見出しは記事ページの右側に表示され、目次として機能します。

ある程度小さなまとまりで区切り、言葉はなるべく簡潔かつわかりやすくしましょう。
マークダウンでは階層を意識すると見やすくなります。とはいえ、あまり深くなってもわかりづらいので、同列のものは同階層に並べるというくらいの意識でいいかなと思います。
記事を書き上げた後は、まずはこの目次がわかりづらくなっていないかチェックするようにしてください。

「はじめに」「おわりに」はお好みでどうぞ。私は内容によって書いたり書かなかったりです。

コードについて

マークダウンは必須

コード直書きはやめてください……。
また、ファイル形式を設定するだけで格段にコードが見やすくなるので絶対に入れてください。名前はファイル名や簡単な説明を書いておくとわかりやすいです。

拡張子指定なし

class User < ActiveRecord::Base
  has_many :articles, dependent: :destroy
end

app/models/authentication.rb

# ファイル名を書くと、拡張子で言語を判別してくれるclassUser<ActiveRecord::Basehas_many:articles,dependent: :destroyend

Good

articles=user&.articles

個人的に、URLのクエリが見やすいマークダウンが欲しいので実装待っています。

過不足なく書く

例えば、「user.rbに以下の部分を追加してください」とだけあったらどうでしょうか。

Bad

authenticates_with_sorcery!has_many:authentications,dependent: :destroyaccepts_nested_attributes_for:authentications

よくわからない人は、こんな風に書いてしまうかもしれません。

user.rb

classUser<ApplicationRecordendauthenticates_with_sorcery!has_many:authentications,dependent: :destroyaccepts_nested_attributes_for:authentications

ということで、ネストについては特に丁寧に書いたほうがいいです。多くの初心者はこのBadのような書き方によって死んでいると思っています。
コメントアウトで補足するとなおいいです。丁寧すぎて悪いことはないです。

Good

classUser<ApplicationRecord# 以下の三行を追加authenticates_with_sorcery!has_many:authentications,dependent: :destroyaccepts_nested_attributes_for:authenticationsend

また、もしかしたら手元のコードでは使っているのかもしれませんが、関係のない記述は省くか置き換えるかしましょう。突如知らないgemのメソッドなどが出現すると戸惑います。
省かない場合は、少なくとも注釈を入れてください。

必要な情報

動作環境

これは本当に書いてください。主要なものについてはバージョンも書いてください。
何を書けばいいかわからないなら、とりあえず登場するもの全部書くくらいでいいです。

参考リンク

読み手からすると、誰が書いたかわからない記事に対しては基本的に懐疑的です。なるべく根拠となる一次情報に当たりたいので、リンクを貼ると親切です。
また、参考にした記事を貼っておくと、どこまでがあなたの判断で書いた情報なのかということがわかります。後々自分が修正しようとしたときも楽です。

エラー文

私は実装時に出たエラー文の引用とその解決法をなるべく書くようにしています。自分で検索してすぐに解決したものは不要ですが、未来の自分や同じように困った人が調べたときに検索に引っかかるといいなと思うからです。
ただ、詰め込みすぎると記事の内容がブレるので、用法と容量にはお気を付けください。
また、ログにはユーザーネームやトークンなどが書かれていることもあるので、コピペする際には注意してください。