この記事のゴール
記事を書くなら、多くの人にとって嬉しい形で伝わるように、最低限気を付けたほうが良いポイントを伝えること。
モチベーション
- 後から見返した時に、何が言いたいのか、読みやすい記事にしたい
- 読み手にとって失礼がないような記事を書きたい
お品書き
- 良い記事を書くためのロードマップ
- 用語を正確に
- 目的を明確にする
- 具体的な例を入れる
- 技術系の記事に求められる要素
- 前提となる環境を列挙する
良い記事を書くためのロードマップ
いくら尖った技術の事しか扱わないと言っても、人対人なので最低限のお作法を身に着けた上で発信したいですよね。
ということで、記事を書く上で何を意識すべきかをピックアップしてみました。
用語を正確に
用語とは？ 例えば Ruby on Rails とかDDDとかPythonとかのそれに当たります。
一口にPythonといっても, バージョン2系と3系で大きく違いますし、ドメインが〜○○という時のドメインとは何文脈のドメインなのかを枕言葉として添えておかないと読み手に誤解を与えかねません。
プログラミングに関する用語は特に抽象的なものだったり、企業によって解釈の違いがありますので、客観的にみて誤解されそうであれば、図やwikiなどを用いてみることをオススメします。
目的を明確にする
極めてシンプルですが、最初にこの記事は何を目的として書かれているのかを宣言しておくことが大事です。
メリットとして
- 書き手が余計な情報を省くことができる(記事の書きやすさに貢献)
- 読み手はパッと見た瞬間に欲しい情報が書かれているかどうか判断しやすい(記事の読みやすさに貢献)
Qiitaであれば、記事のタイトル = 目的 くらいの気持ちが良いのではと思います。
覚書の情報なのか、困りごとを一般的に解決したいのか大違いですよね。
具体的な例を入れる
エッジケースな記事なら、コピペで使えるコードを載せておくのがベターですね。
抽象的な話（アーキテクチャなど）でも、サンプルコードがあったほうが、ステップ・バイ・ステップで理解が進められるので、
読み手からするとありがたいですね。
もちろん、コードにまで落とし込まなくてもUML図などを用いて視覚的に理解しやすいようにするのも手です。
要は、読み手に疑問を残さないようにしておくことが重要ということ。
技術系の記事に求められる要素
前提となる環境を列挙する
列挙するポイントは、その環境が異なった時に書いた内容の期待値が変わる恐れがあるかどうかです。
フロントエンドだと、どのブラウザの何バージョンかですし、
バックエンドはOSやPCのスペックなど。
AWSやGCPなどのクラウドを前提とする場合、具体的に書くほど再現性が高まるので気にした方が良いでしょう。
一例ですが、AWSでNode.jsのAPIサーバーを建てる場合は
- EC2のインスタンスタイプ
- Node.jsのバージョン
- npmのバージョン
は最低限あった方が嬉しいですね。
逆に、この手順通りにすれば確実にこうなるよ、と誘導するやり方も良いですね。