「エンジニアのブログ始め方」の記事 - Crieit

ターゲットを考えてタイトルを考えよう

2019-05-07T21:04:23+09:00

タイトルは文字数も少ないですが、人はそれを見てまず記事を読むか読まないかを決めてしまうため奥が深く、考えるのには意外と時間がかかります。色々とタイトルを決める考え方はあるためいくつかあげてみます。

伝わるかを考える

エンジニアが記事を書くとなると、やはりプログラミングや何らかのソフトウェアやライブラリなどの、人によっては良くわからないワードなどが出てきます。

例えば僕が過去に書いた記事で、Puppeteerについて書いた事がありました。具体的にはPuppeteerでスクリーンショットをとる記事なのですが、例えばそのものズバリのタイトルにすると「Puppeteerでスクリーンショットを撮る」となります。

しかし一つ考えておきたいのが、Puppeteerを知っている人がどれだけいるのか、ということです。

知ってる人からすると「お、面白そう」と感じて見てくれるかもしれませんが、知らない人は「ふーん、なんかのデスクトップ用のよくあるようなフリーソフトかな」と思ってしまう可能性もあると思います。

このように、専門用語や固有名詞をタイトルに入れてしまうとそもそも何の記事なのか、ぱっと見で伝えられない可能性が出てきます。そのため上記の例でいうと僕は「Node.jsでChromeを動かしてスクリーンショットを撮る」のようなタイトルを付けました。PuppeteerよりもNode.jsとChromeを知っている人の方が多いと思ったからです。

ちなみにこの記事はあまり興味を持たれなかったようでさほど閲覧されませんでしたが、とはいえ、適当にタイトルを考えるよりは一度「本当に伝わるのか？」という疑いを持ってタイトルを見直すようにした方が良いのではないかと思います。

誰に伝えたいのかを考える

上記の例で、Puppeteerを知っている人だけにこの情報を伝えたい、ということであればそのものズバリPuppeteerをタイトルに入れる形でも問題ないと思います。Puppeteerを知っている人には有益な記事でも、知らない人には全く価値のない記事の可能性もあるためです。

かならずしも全ての記事が幅広い層に見てもらう必要のある記事ではないと思いますので、ターゲットがあるのであればそちらを優先してタイトルを決めてしまっても良いと思います。

文字数

色々な場所に表示されるタイトルの文字数というのは決まっています。大体30文字までにしておくとどこでも尻切れにならずに表示されますのでそれを意識してみましょう。

また、どうしても長くなってしまう場合は重要な内容を最初の30文字くらいに入れておいて、あとはまあ切れてしまって読まなくても伝わるし、読んでから伝わればいい、みたいな形にしておけばさほど支障はないと思います。

Crieitでは記事入力画面でタイトルの文字数を表示しているので是非参考にしてみてください。

その他、タイトルの付け方は色々なバリエーションがあります。めちゃくちゃ草をはやして気になる感じにしたり、「～～の７つの方法！」のようなものなど、世の中にあふれている多くの記事を参考にしてみると目を引きやすいタイトルの作り方がわかってくると思います。ただ、エンジニア向けのものであればさほどそのようなタイトルの決め方をする必要もないのでは、と個人的には思います。僕は結構余分な装飾をせず、短いタイトルの中になるべく必要な情報を詰め込みたいタイプですので、そういったことはしません。

そのあたりは個人の色や読者のターゲットによるものになりますので、適宜自分にあった形を決めていくと良いのではないかと思います。

すぐに決めなくても良い

記事は最後に投稿する時に決めればよいので、記事の書き始めなどで無理に決める必要はありません。なかなか決まらなければ空欄にしておいて、最後に記事を読み返してみて、そこで考えてみるのも良いと思います。どちらにしろ、決めていたとしても最後に見直して見たほうが良いと思います。

概要を意識しよう

2019-04-26T09:29:15+09:00

記事を書くときは概要、つまりメタタグのdescriptionがどのようになるかを意識しましょう。昔は検索結果に表示される内容としての用途が主でしたが、現在は記事をTwitterなどでシェアした際に本文の一部として表示されるということもあり、有用さが増してきていると思います。みなさんもよく見ると思いますが具体的には下記のようなものです。

画像の下に表示されているのが分かると思います。

Googleの検索結果は人が能動的に探しに行くものですので「実際にページを開いてみるため」の判断材料なのですが、Twitterの場合は「全く考えもしなかったところに興味をもたせる」というところで役割も異なっており、非常に有用なものです。ここに興味を持たせるための内容を詰めておくことがわりと重要だと思います。

長さ

通常、descriptionの長さはGoogleの検索結果に合わせて300文字程度とかがいいという情報があります。もちろんそれはそれで重要なのですが、さらにシェア用の60文字程度には、記事に興味を持ってもらうための内容を詰めておくことがベストだと思われます。

概要の書き方

どの部分が概要として使われるかはブログやサービスによって異なります。

一般的なブログや記事投稿サービスの場合

一般的なサービスの場合、記事の先頭がdescriptionとして使われることが多いと思います。当サービスもその様になっています。この場合、記事の書き出しに自己紹介や最初の一ネタを書きたい場合などがあると思いますが、それだとツイートなどには内容と関係ない概要が表示されてしまいもったいないです。

我慢してまずはdescriptionに載せたい部分を書き、その後に補足として書くようにしましょう。

WordPressの場合

WordPressの場合はプラグインを使ったり改造したりすることで直接設定したりすることができるようになります。そのようにしている場合は本文は自由に書いて問題なさそうです。

困っている人がたどり着ける記事にしよう

2019-04-21T23:42:56+09:00

もしせっかく記事を書くのであれば、その記事を必要としている人がたどり着きやすいような記事にしておきましょう。せっかく問題解決の記事を書いても、その問題で困っている人がその記事にたどり着けなかったり、有用な考察を書いたとしてもそれを参考にしたい人がたどり着けなかったらもったいないです。

エラーメッセージはなるべく書いておきたい

なにかの問題が起きた時に表示されるエラーメッセージは共通言語のため、ブレが少ないです。行番号や変数名がエラーメッセージ内に含まれていれば多少のブレはありますが、それ以外のところは固定文言のため検索で非常にひっかかりやすいです。そのため困っている人がたどり着く可能性が非常に高くなりますので可能な限り記事中に書いておきましょう。

どのように検索されるか想像する

ある記事を書いた場合に、その情報を必要としている人がGoogleでどのように検索するかを想像しましょう。例えば、エンジニアがブログを書きたくなった時、どのように検索するでしょうか？

「ブログサービス」で検索するかもしれませんし、エンジニア向けのものを探す場合は「エンジニアブログ」や「エンジニア記事書く」、「技術記事」かもしれません。「コード書けるブログ」とか、「Markdown ブログ」のように機能を重視して検索するかもしれません。

どれもそのあたりのワードが記事中になければ検索に引っかかる確率が減ると思いますので、記事中でそれぞれについて言及しているのであればきっちりそれらのワードを入れておきましょう。

正式な記事であれば表記揺れをなくしたほうがよいという方もいるかもしれませんが、個人的には問題解決系の記事であれば表記揺れは無視し、むしろ時々言い回しを変えてどんな類似ワードの検索でもたどり着けるようにしてあげた方が親切だと思います。（ある程度はGoogleが吸収してくれますのでやりすぎる必要はないと思いますが）

よくSEOで重要なワードを記事中に何度も出現させてSEO力を高める、のような話も聞きますが、個人的には全く重要ではないと思っています。普通に人と話して問題を解決してあげる時でも、相手が意味を理解していなかったら「どういう意味？」と聞いてくると思いますし、それに対して言い回しを変えて教えてあげると思います。しかし、検索ではそんなインタラクティブなやり取りはできませんので、あらかじめ必要な言い回しは記事中に用意してあげる必要があるのではないかと感じています。

まとめ

とにかく、検索する人のことを考えてあげて、検索する人にとって優しい記事にしましょう。検索している人は、探しているものにたどり着きたいのです。

記事を書くネタの探し方（日常のプログラミングから）

2019-04-15T22:26:25+09:00

いざ記事を書こうと思うと、当然書くためのネタが必要になります。一番簡単なのは自分が普段書いているプログラムからネタを見つけることです。仕事であっても趣味のプログラムであっても、そこで書いたり調べたりしたことは記事のネタになることが多く、一番身近で、且つ既に自分で書いたもののため記事にしやすいです。

つまづいた点を書く

思いがけずエラーが出たりすればそのエラーの内容や、解決方法を書けばあっという間に役に立つ記事が出来上がります。

更に具体的にどういった理由でそのエラーが起きたのか、なぜその解決法で解決できるのか、もしくは現時点では解決方法がないとか、その上で自分で試しに行ってみた方法で一応は動くようになったとか、そのあたりの一部始終を書くことでそれなりの記事になっていきます。

しかもつまづいた点は他の人も困っている可能性があるため需要があります。検索流入を増やす可能性も高くなります。

新しいものを使ってみた話を書く

プログラムを書いていると、実装する機能のために今まで使ったことのないライブラリを使う必要出てくる場合があると思います。特に最近出てきたばかりのライブラリ等だったりすると、まだ世の中に使ったことのある人が多くなかったりします。そういったものは興味を持たれる可能性が高くなります。

普段はあまりそういったものに触れる機会はないかもしれませんので、記事を書くために寄り道をしてプログラムを書いて試していったりすることになるとは思いますのでちょっと大変にはなりますが、どうしても直近で書けるネタが無いときや、自分の趣向的に気になって使いたいと思っていたライブラリだったりする場合にこの方法を取ると良さそうです。

ライブラリだけでなく、クラウドのサービスや、アプリなど、色々なものを触ってみて書くこともできます。

当たり前のネタでも書いてみる

普段のプログラミングの中で、「これは当たり前のことだしいまさら書いてもなぁ…」ということがあると思いますが、それでもどんどん書いてみることをおすすめします。

というのも、自分にとっては当たり前のことであっても、まだその技術に達していない人や、少し普段使っているプログラミングの方向性が違う人からすれば、それはまだ知らない技術だったりすることもありますので、必ずしもそれは「当たり前」とは限りません。

むしろ、世の中の熟練度ピラミッドから想像すると難しいことを調べるよりも当たり前のことを調べる人の方が多いはずですので、気にせず書いてみることが重要となります。

すごく短い記事でも大丈夫

2019-04-12T23:51:45+09:00

記事を書く時、必ずしも頑張って長文の記事に仕立て上げる必要はありません。例えばそもそも、あるエラーに対しての対処方法を書くような記事の場合、無駄に長々と関係のない説明を書いても読むのが辛いだけで本質的ではない場合もあります。ですので例えば、こんな構成の短い記事でも問題ないです。

～～をしていたら下記のようなエラーが出ました。

Error: This is a special error code E2234 (aewfew is undefined)

原因として、～～のライブラリを使っている場合は～～の設定を書いておかないとエラーが発生してしまうため、下記のような設定を追加しておきます。

  setting: true,

こんな感じでも十分です。とにかく書きのこしておいた方が良いかな、と思ったことは短くてもいいのでガンガン記事にしてしまいましょう。もっと深く掘り下げた情報も追記したい、参考となる関連情報も書いておきたい、などがあれば、後で思いついたときにでも追記はできますので。

とくにエラーメッセージはそのものズバリで検索されることもあるので、それと改善方法さえ書いておけば困った人が検索でも引っかかりやすいです。実際に、僕も自分で書いた記事と同じエラーを出して検索し、自分の記事にたどり着いたこともあります。ですので自分のためにも他の人のためにも、とにかく書き残しておきましょう。

プログラムのコードを書こう

2019-04-11T22:44:15+09:00

やはりエンジニアが記事を書くとなるとプログラムのコードを書くことが必要になってくると思います。Markdownであればだいたいコードハイライトに対応しているため、簡単に色付けを実現することができます。

具体的にはバッククォート３つを並べた行で囲まれた行はコードとして扱われます。

1 | ```javascript
2 | function test(a) {
3 |   console.log(a)
4 | }
5 | ```

上記のように書くと（行番号部分は不要です）下記のようになります。

function test(a) {
  console.log(a)
}

最初のバッククォート３つのあとには言語名を書くことでその言語の色付けに対応しています。例えばphp, ruby, javascriptなどです。他にも色々ありますので必要なものがあれば調べてみてください。

注意点

間違えてパスワードや鍵などをそのままコピペして投稿してしまうと危険ですので、そのあたりは適当な文字に置き換えておきましょう。

基本的な体裁 - 見出しと段落

2019-04-10T23:57:02+09:00

Markdownで記事を書く場合、最も基本的であろうという体裁の作り方が二つあります。それは「見出し」と「段落」です。

見出し

↑のように、見出しというのはHTMLでいうh1タグとかh2タグで表現されるもののことです。Markdownの場合、# を使って書くことができます。

# h1
## h2
### h3
#### h4

一般的なブログサービスの場合、h1は記事のタイトルに使われたりします。そのため、記事中ではh1は使わずh2から使い始めたほうが良いでしょう。（ただしサービスによっては自動的に変換してくれたりするものもあるようです）

無駄に改行せず段落を使う

昔は改行をたくさん使って改行芸のようなことをする風習がありましたが、最近はPCとスマホ両方で表示できるようなレスポンシブ対応が標準となってきている関係で、あまり改行は望ましくないものになっています。

そのかわり、Markdown等の場合も改行を二つ連続で書くことで、段落わけを行うことができるようになっています。HTMLで言うところのpタグになります。そのため無駄に改行を使わず、キリの良いところで段落分けして読みやすくする、という書き方にしていきましょう。

とりあえずこの見出しと段落さえ覚えておけば基本的な文章は書けると思います。

プログラム言語やフレームワークのバージョンを書こう

2019-04-09T23:40:31+09:00

技術的な記事を書く時、まずは使ったプログラミング言語やフレームワーク、ソフトウェア等のバージョンを忘れずに書くようにしましょう。

なぜバージョンが必要か

例えば同じPHPでも、PHP5.6とPHP7.3ではそもそもできることが異なっていたりします。

「PHP＋Laravelでこんなライブラリを使ってみました！」という記事を書いていたとしても、それが最新のPHP7.3＋Laravel5.8でしか動かないライブラリだった場合、記事を見た閲覧者が同じことを試して見ようとしても、PHP5.6＋Laravel5.5とかだったらそもそも動きません。なんでだろう…と悩んで時間を無駄に浪費してしまうことになります。

また、「こんなエラーが出たので解決した」という記事を書いた場合も、バージョンによってはそもそも発生しなかったり、解決方法が異なっていたりする可能性もあります。

「何の問題もなく簡単にできました！」と書いたのに、他の人が試してみるとエラーばかり出て全然進めない、GitHubのIssueを見てみると最新のバージョンだとエラーが報告されていてまだ解決していない…なんてこともあります。

どのように書けばいいか

プログラミング言語の話だけであれば最初に「PHP7.3を使っています」とでも書いておけば良いと思います。言語、フレームワーク、ライブラリと、色々なものを使っている場合はリスト表記で書いておくと良いでしょう。Markdownの場合リスト表記は下記のようにアスタリスクやハイフンで記述できます。

* PHP7.2
* Laravel5.8
* Bootstrap4.3

このように書くと

PHP7.2
Laravel5.8
Bootstrap4.3

のように表示されます。

Markdownで書いてみよう

2019-04-09T23:38:18+09:00

技術系のブログを書く場合、Markdownで書くのがおすすめです。Markdownというのは、記号を含めたテキストの書き方で、簡単に見出しや強調など、文字の装飾、コード表記を行うことができます。

例えば強調する場合は

**ここを強調**する

のように書くと

ここを強調する

のように表示されます。

## 見出しです

のように書くと

見出しです

のように表示されます。

はてなブログ、Qiita等、技術系の記事を書くことができる様々なサービスで使われており、GitHubのREADMEも書くことができるため、とにかく一番オススメの書き方になります。

色々な書き方がありますので下記などで見てみてください。

Markdown書き方メモ - Qiita