Qiitaの記事を書く際に気をつけようと思ってること

はじめに

私がQiita等の技術サイトで記事を書く際に気をつけるメモ的な存在になります。
いわば私のリファレンス・マニュアルです。
加えて、みなさんの足がかりになれば幸いです。
これから書くことは、「私」が気をつけることであって「皆さん」が記事を書くときに「こうしなさい」と言ってるわけではないことを予めご了承ください。

画像や文字装飾が殆どないので読みにくいかもしれません。気が向いたら編集/追記します。

参考文献等

本記事は私オリジナルの意見ですが、似たような記事がありましたのでご紹介させていただきます。

• 個人的な良い記事のガイドライン = 2ヶ月前の自分が泣いて喜ぶような記事を書く - Qiita
• Qiitaで技術系の記事を書く時に気をつけていること - Qiita
• Qiitaで良い記事を書く技術 - Qiita
• 【Qiita】今日からできる！見やすい記事の書き方 - Qiita

タイトル

簡潔なタイトルを心がけるようにしています。
「環境」「言語」「何をした」 が入ってるといいかと思います。
アクセスを意識したような抽象的なタイトルは、開けば自分が欲してる情報がなく「釣られた」状態になるので個人的には好みません。

目次を書く

長い記事は目次を書きます。
Qiitaは記事右にナビゲーションがあります。
Markdownで#を使って見出しを設定できるので、適切に設定します。

本文の最初にも手作業で目次を書く場合は一長一短があります。

メリット
・ナビゲーションだと冗長になっている見出しを簡略化することができる。
・ある程度見やすくなる可能性がある。

デメリット
・手作業になるので管理が煩雑 →
・本文上部が見出しに占有され、可読性が損なわれる可能性がある。

<追記:2021/03/18>
Visual Studio Codeを使ってる場合はMarkdown(Marketplaceリンク)という拡張機能を入れると簡単に目次が作成できるようです。
他にも簡単にMarkdown形式の目次を作成できる方法があるかと思いますので、デメリットの「管理が煩雑」を削除しました。
(参考)Visual Studio Code の Auto Markdown TOC プラグインという目次作成ツールが神な件 - Qiita

環境を明記する

自分の環境はどうなのかを明記しましょう。
ソフト名だけでなく、バージョンも書きましょう。
記事の最初の方に書いたほうが好ましいと思われます。
（読者が求めてる情報を最初に提示することで、無駄な時間を減らせる）

日付を書く

Qiitaは更新日時が自動で付与されますが、トレンド技術等の記事は流れが早いので別途本文に日付を書くことを検討します。

結果は先に書いてもいい

問題に対して解決した系の記事で結果が端的にかけるのであれば、
結果を先に書いても構わないと思っています。
読者はどうすれば解決するかを見に来たのであり、投稿者が「こんなに頑張ってやっとたどり着きました」という自慢を見に来たわけではありません。困ってるから見に来たのです。
ですから、結果を先に書く手法は大いにありだと思っています。

結果を先に書くことへの考えられるデメリット

• 読者が経緯を読まずにコマンドだけをコピペしてしまうので、本質の理解を阻害する。
  • そういう人は最後に結果書いてもスクロールで飛ばします。
    その行動に対して良い悪いを議論してるわけではなく、実態がそうなってしまっているのであれば
    先に書いても構わないと考えているだけです。賛否両論あるでしょう。
  • そもそも調べに調べて到達した技術者であれば経緯は不要の場合もあります。

結果を先に書けば、
経過を見なくていい人も、経過を見たい人にも両方にとってメリットではないでしょうか。
まさか技術記事でネタバレされたくないと考える人はいないでしょう。

間違った行動が必要なのか

私は単純なコマンドでしたらとりあえず端末にコピペすることがままありますが
（ここでも、この行動の良し悪しの議論はしません。）

＊＊＊＊ と打ちます。
これでは出来ませんでした。
正解は＊＊＊＊です。

みたいな書き方ですと、間違ったところいるのかなと思ってしまいます。
パソコン教室に来たわけじゃないんですよね。

※初心者向けの記事では理解を促すためにも良いと思います。
　問題解決系の記事ではこの書き方は相応しくないと思ってます。

本文中

リンクの貼り方

長いURLはMarkdown記法でリンクのテキストを記載します。
ただし、短いURLやドメインのみの場合はテキスト＋URLを別に書いたほうがわかりやすい場合もあるかもしれません。
例えば

Google
と書いてあるより、

Google- http://google.com

とあるほうがURLに透明性がありわかりやすいと私は感じます。

注釈を多用しない

QiitaではMarkdownで注釈をつけることができます「*1」のようなものです。
私は本を読むときにも思うんですが、わざわざ別のページに行くのがめんどくさいです。
注釈が有効なのは、エイリアスのように複数箇所で*1のような説明がいる場合でしょう。

しかし1箇所しかない場合はその有用性は低いと思います。
また、開くまで内容がわからないのが最大の欠点です。
「*1に～～～の説明をしています。」と書いてあるならまだしも、「～～は～～である。*1」の場合、
その注釈が自分にとって有用な情報であるかがわからない状態でリンクを踏むことになるので、
どうでもいい情報が乗っていた場合無駄足を踏むことになります。
また、Qiitaの注釈はページ遷移を伴うため、操作が2回増えます。（リンク踏む→戻る）

• もし注釈が必要であれば、まずその注釈は本当に必要なのかの再検討
• 必要であればすぐ下に説明を書く
• 長くなるのであれば折りたたみを利用する。

という方針で書いていきたいです。

（例外）
「注釈＝参考記事等のリンク」 等に目的を絞るのであればアリだと思います。
「本文中に書くには冗長すぎる情報」かつ「ルールを決めている」のであればアリという考えです。

コード挿入に全てを頼らない

Qiitaではコードを埋め込むことができます。
コードを埋め込むときに設定できる情報は2つあります。

1. シンタックスハイライトする言語
2. 左上のラベル

この2つは必ず設定します。
まず、適用したい言語を適切に設定します。
これを設定しなければコード挿入のMarkdownを使う意味がありません。
次にラベルを設定します。
今どのファイルを編集しているのか、見ているのかを明確にさせます。

次に挿入したコードの中身ですが、
「ターミナル端末の画面出力のコピペ」
や
「ファイルの一部分を切り出す」
といった行為は一度立ち止まって考える必要があります。

ターミナルのコピペに関しては本当にその情報が必要なのでしょうか。
読者はその「画面出力の文字列」を「コピー」する可能性があるんでしょうか。
出力された文字を「見せる」だけであればターミナルのスクリーンショットのほうがまだ見やすいのではないでしょうか。

出力された文字を貼ることによって、同じ問題を抱えた人間を検索で流入させることができるかもしれませんが
該当エラー文だけ本文に記載することでことたりるでしょう。

また、プロンプト表示部分「$」や「#」は不要です。
コマンドをコピペするときに邪魔になります。
(rootで実行する必要があれば文章で明記する。)

ファイルの一部分を切り出してコード挿入するのもよくありません。
投稿者はどのファイルの部分かを知っているかもしれませんが、読者は知りません。
急に一部分現れたらわかりづらいです。
～省略～ ～中略～を使ってこのファイルの一部分であることを明確にします。
行数を明記するのも有効でしょう。

技術記事は「見せる」＋「実行させる」が基本だと思っています。

GIF画像について

メリットも有りデメリットもあります。
【メリット】

• 視覚的に訴えることができる
• 再生ボタン等の操作が不要
• デザイン系の記事の場合アニメーションを使って動的に見せることができる

【デメリット】

• 勝手に再生される
• 勝手に再生されると、どこがはじめかわからない
• シークバーみたいなものがないのでGIF画像がいつ終わるかわからない

GIFを使うときは、伝えやすい動画を作れるように心がけます。

記事全般

記事はアップデートさせる

コメントで指摘があったものなど、コメント内で「謝罪」「訂正」を行うのは別にいいですが
記事にフィードバックさせましょう。
また、古い情報は基本的にいらないです。
（歴史的文献を残したいのであれば別ですが）
削除もしくは新しい情報を上、古い情報を下にしましょう。
そして情報を更新した日時は記載しましょう。

「古い情報」
「新しい情報」

という順番だと、混乱します。また、古い情報を読まなければいけない手間が増えます。
新しいものを上にします。

備忘録という免罪符を使わない

備忘録という言葉を使用してる人を非難するわけではないですが
その人にとっては本当にただの備忘録（個人的メモ）であり、誰かに読ませることを想定していないのでしょう。
問題を抱えて解決できたからとりあえずコードを張ってるのでしょう。
そして誰かが同じエラーにたどり着いたら見てくれたらいいなくらいの気持ちでしょう。

そういう使い方もあるかと思います。

ただ、自分が書くときは備忘録という言葉に頼らないようにしたいです。
備忘録はメモであり、ローカルのテキストファイルにでも書きます。

誰かに読ませたいからQiitaに書くのであって、わかりやすい記事を目指していきたいです。

おまじない論法をやめる

最近聞かなくなりましたが、わからないならわからないと書くべきです。
もしくは正しく解説されているサイトのリンクを貼るなどしたほうが親切です。
おまじないと言って濁らせて中途半端に書くくらいなら書かないほうがいいでしょう。

「，」「．」

論文を書かれている方や、何か特定のフォーマットが指定された文書を書くことが多い方は句読点の入力を変更しているため、「、」「。」以外の句読点で文章を書く場合があります。
ですが、できることなら「、」「。」で合わせてしまったほうが見やすいかと思います。
まあでもこれは人それぞれの感性によりますね。

参考記事の位置

考えられるパターンは3つです。

1. 記事の最初に参考にしたページのリンクを貼りまくる
2. 記事の最後に参考にしたページのリンクを貼りまくる
3. 記事最中に都度参考ページを貼る。

また、参考度合いにも2パターンあると思っています。
A. 参考記事をまるごと参考にした場合
B. 参考記事の一部分が、実現したいことの手段として参考になった場合

参考記事の種類ごとに考えます。

【A記事】
最初か最後に統一して書くのがベターでしょう。

【B記事】
本文中に都度貼るか、A記事と合わせて最初か最後に記載します。
（最後のほうが良い気がします。）

本記事は検索してみるとたくさんの似たような記事があったため
先駆者へのリスペクトを込めて最初に参考記事を記載させていただきました。

B記事を最初か最後にまとめて書くパターンですと記事中のどの部分をどのリンク先で参考にしたかがわかりづらいため、手間をかけれるなら注釈等を使うのもいいでしょう。

記事を書き終えたら

記事を読み返す

5回くらい読み返して誤字脱字等のチェックをします。校正者は自分しかいません。
その日に投稿するのではなく、次の日に読み返してみるとおかしな表現があることにも気づくかもしれません。

限定公開にしてみる

編集画面のプレビューだとわからない部分が見えてくるので限定公開にして最終チェックをします。

他にも

文章の構成や、漢字をひらくとか、適度な改行をはさむとか色々あります。
国語の問題に近いので今回は取り上げませんでした。参考記事を見てください。

最後に

偉そうに書きましたが、私自身も気をつけようと思ってるだけで、すべてできているというわけではありません。
また、私はライター経験はないですし、個人ブログの運営もしていません。ただの読者です。
ただの読者なりに、記事はこうあるべきと考えました。
そしてこの考えは発展途上であり今後変わる可能性もあります。

ここまでルールをガチガチに決めてしまうと今後自分の首を絞めてしまうことがあったり、記事というアウトプットが出しづらくなってしまっては本末転倒ですので、各人の中でぼんやりとルールを決めていれば良いのかなと思います。

以上です。

よかったらTwitterフォローしてください😊
https://twitter.com/daemokra