はじめに
以前、「Qiitaはいいぞ」という話を、私が通うスクールであるRUNTEQの雑談会でしました。
- LGTMやストックによって誰かのためになっている実感が生まれやすい
- 強い人からコメントをもらいやすいため、まとめる以上に自分の勉強になる
- SEOが強いので、「解決法に出会えなかった過去の自分」が記事に辿り着きやすい
このようなメリットがあり、また新たにブログを開設しなくてもいいので、簡単に記事を書くことができます。
しかし、上述のように、記事に行き着く人が多かったりある程度コミュニティの一面もあります。自己満の場所ではないため、人に見せることを前提とした記事を書く必要があります。
そこで、自分が意識していることをまとめていたら、「これだけで記事にできるんじゃないか？」と思ったので残しておくことにします。
とりあえずこれだけ気をつけておけばいいんじゃないかなという内容です。
せっかくなので、記事タイトルは煽り気味に付けさせていただきました。今日からできます。
この記事の対象者
- Qiitaで記事を書いたことがない。
- どんなことを意識して記事を書いたらいいのだろう？
- 初めて記事を書いてみたものの、なんか見づらい気がする。
意識すること
タイトルのわかりやすさ
タイトルは記事の顔です。シンプルな言葉で何についての記事かわかるようにしましょう。
「勉強○日目に学んだことアウトプット」のような、見る人に何の情報も与えないタイトルはやめた方がいいです（個人ブログならいいと思います）。
私は基本的には下記のように書いています。フォーマットをある程度パターン化するとタイトルを付けやすいのでおすすめです。
- 【Rails】一対一対多のアソシエーション
- 【MySQL】Mysql2::Error::ConnectionError 対処法
- 【Rails】SorceryでTwitter認証
- 【SSH】公開鍵認証とEC2について
- 【Rails】入力された値を元にGETリクエストを送ってjsonを取得し、DBに保存する
このような書き方でなくとも、技術の名前をタイトルに書いていない記事はほとんどないと思います。
トレンドにあるような記事のタイトルは、煽り気味で目を引くタイトルが多いです。が、個人的には取り立ててそれを踏襲する必要はないかなあと思います。
見出しの構成
見出しも重要です。
内容が短いなら無くてもいいと思いますが、ある程度構成のある長い記事なら必ず付けてください。この見出しは記事ページの右側に表示され、目次として機能します。
ある程度小さなまとまりで区切り、言葉はなるべく簡潔かつわかりやすくしましょう。
マークダウンでは階層を意識すると見やすくなります。とはいえ、意識しすぎて深くなってもわかりづらいので、同列のものは同階層に並べるというくらいでいいかなと思います。
記事を書き上げた後は、まずはこの目次がわかりづらくなっていないかチェックするようにしてください。
「はじめに」「おわりに」はお好みでどうぞ。私は内容によって書いたり書かなかったりです。
ちなみに、目次では最初の見出しの大きさを基準としてネストされるので注意してください。
コードについて
```は必須
コード直書きはやめてください……。
また、ファイル形式を設定するだけで格段にコードが見やすくなるので絶対に入れてください。名前はファイル名や簡単な説明を書いておくとわかりやすいです。
# このようにただの文字で表示される
class User < ActiveRecord::Base
has_many :articles, dependent: :destroy
end
# ファイル名を書くと、拡張子で言語を判別してくれる
class User < ActiveRecord::Base
has_many :articles, dependent: :destroy
end
# sh:EC2インスタンス内で と書くとこんな感じになるので簡単な説明などに使える
[username@ip-10-0-11-209 ~]$ mkdir .ssh
[username@ip-10-0-11-209 ~]$ chmod 700 .ssh
[username@ip-10-0-11-209 ~]$ touch ~/.ssh/authorized_keys
[username@ip-10-0-11-209 ~]$ chmod 600 ~/.ssh/authorized_keys
個人的に、URLのクエリが見やすいシンタックスハイライトが欲しいので実装待っています。
過不足なく書く
例えば、「user.rbに以下の部分を追加してください」とだけあったらどうでしょうか。
authenticates_with_sorcery!
has_many :authentications, dependent: :destroy
accepts_nested_attributes_for :authentications
よくわからない人は、こんな風に書いてしまうかもしれません。
class User < ApplicationRecord
end
authenticates_with_sorcery!
has_many :authentications, dependent: :destroy
accepts_nested_attributes_for :authentications
ということで、ネストについては特に丁寧に書いたほうがいいです。多くの初心者はこのBadのような書き方によって「どこに書けばいいの？」となったと思っています。私は死にました。
コメントアウトで補足するとなおいいです。丁寧すぎて悪いことはないです。
class User < ApplicationRecord
# 以下の三行を追加
authenticates_with_sorcery!
has_many :authentications, dependent: :destroy
accepts_nested_attributes_for :authentications
# 以下省略
end
diffを使うのも便利です（ただ、+や-もコピーしてしまうことになるので個人的には好きではない）。
class User < ApplicationRecord
+ authenticates_with_sorcery!
+ has_many :authentications, dependent: :destroy
+ accepts_nested_attributes_for :authentications
# 以下省略
end
また、もしかしたら手元のコードでは使っているのかもしれませんが、関係のない記述は省くか置き換えるかしましょう。何も説明なくgemのメソッドなどが出現すると戸惑います。
省かない場合は、少なくとも注釈を入れてください。
「過不足なく書く」に関しては、対象者のレベルにもよります。
ある程度その技術に慣れていれば、多少記述が抜けていても読者が補完することができます。ただ、丁寧に書きすぎて読者が困ることはないと思います。
必要な情報
動作環境
これは本当に書いてください。主要なものについてはバージョンも書いてください。
何を書けばいいかわからないなら、とりあえず登場するもの全部書くくらいでいいです。
参考リンク
読み手からすると、誰が書いたかわからない記事に対しては基本的に懐疑的です。なるべく根拠となる一次情報に当たりたいので、リンクを貼ると親切です。
また、参考にした記事を貼っておくと、どこまでがあなたの判断で書いた情報なのかということがわかります。後々自分が修正しようとしたときも楽です。
画像・GIF画像
「どのようなエラー画面が出たのか」「そのコードで何を実現できるのか」を画像として残すとわかりやすいです。
また、（例えばAWSなど）作業手順を書く場合でも、「〇〇を選択します」より画像に丸印を付けて提示した方がわかりやすいです。
ただわかりやすいだけでなく、サービスのUIが変わったときに判断するのにも役立ちます。文字だけだと「記事ではこう書いているのに見つからない」という悲劇が起きてしまいます。
エラー文
私は実装時に出たエラー文の引用とその解決法をなるべく書くようにしています。自分で検索してすぐに解決したものは不要ですが、未来の自分や同じように困った人が調べたときに検索に引っかかるといいなと思うからです。
ただ、詰め込みすぎると記事の内容がブレるので、用法と容量にはお気を付けください。
また、ログにはユーザーネームやトークンなどが書かれていることもあるので、コピペする際には注意してください。
おわりに
これらのことはもう既にできているという方も多いと思います。
実際、意識すればすぐにできることばかりなので、是非心がけてみてください。また、記事を投稿したことのない人もこれを機にQiitaデビューしましょう！
私も記事を書く上で足りないところはたくさんありますが、少しでも誰かの役に立てばいいなと思って書いています。
最初の読者は自分自身です。まずは自分が読んで読みやすい記事にすることを目指しましょう。
参考サイト
-
もっとわかりやすく詳しく書かれています。
-
具体的な書き方について
ちなみに、実際の記事を見て書き方を真似したいと思ったときは、こちらからMarkdownを見て参考にできます。
