モバイルアプリエンジニアの山下（@yamshta）です。
LCLでは今年の1月にエンジニアブログ編集部を立ち上げ、『継続』を目標に1年間アウトプットし続けてきました。
この記事は66本目となり、この投稿数は前年の約2倍となります。
個人としては22本を執筆することができ、執筆以外にも編集部の取り組みとして、他のメンバーへの執筆依頼や記事の校正にも挑戦しました。
執筆依頼は、普段ブログを書き慣れていないメンバーにもお願いするため、読者が読みやすい記事をスムーズに執筆できるように、個人的に気をつけていることを執筆ガイドラインとは別に共有しました。
今回は、その内容をこちらでも紹介したいと思います。 個人的な趣向に偏ってしまうため、あくまで参考程度に受け取っていただければと思います。
タイトル編
タイトルは最後に考える
はじめにタイトルから考えようとするとそれだけで時間を使ってしまいがちです
明確なキーワードがあれば、直ぐにハマったタイトルが思いつくかもしれませんが、そうでない場合は一番最後に考えることをオススメします。
大体の場合、記事が書き終わる頃に必然的にタイトルが思い浮かぶことが多いです。
キャッチーなキーワードを入れる
LCLエンジニアブログで今年はてなブックマークを多く頂いた記事を参考に見ていきます。
iTerm2とfish shellを使ったターミナル環境構築のはじめの一歩
こちらは「はじめの一歩」というワードを入れることで、初心者の方にも難易度が低そうなイメージを出すことができました。
「可視化」や「最適化」など時短に繋がる魅力的なキーワードを含むことができています。時短は皆さん大好きですよね。
GASでラクをする技術（Gmail・Google Calendar・RSS編）](https://techblog.lclco.com/entry/2018/03/15/083000)
「~する技術」はエンジニアでは定番のフレーズとなっており、自分もつい見てしまいます。他にも「突撃！隣の〜」などのパロディ的なタイトルにするのはオススメです。
これら以外にも以下の視点で考えるとよいです。
- 数字を含める
- 「まとめ」、「比較」を含める
- 絵文字を含める
構成編
変化を中心に書く
エンジニアブログでは、技術やツールを使用した記事を執筆することが多いと思います。 その際は、その技術やツールを採用してどのような変化があったかを最優先で伝えるのがベストです。手段だけ書いている内に文章が長くなり、満足してしまうことも多々あります。
例えば、ある技術の紹介記事を執筆する場合は、課題 ➝ 紹介（採用理由） ➝ 導入 ➝ 効果 の流れで書くと良いと思います。
大枠から組み立てる
いきなり文章を書き始めるのではなく、段階を追って大枠から構成を考えるとよいです。
以下の記事を例に段階を分けてみます。
例：1日のスケジュールを可視化してタスク消化率の最適化を図る
1. 伝えたいことを明確にする
ここで伝えたいことは以下のことです。
タスク消化率を最適化させたノウハウを伝えたい
これが定まっていないと、執筆途中で内容が反れてしまうこともあるので一番始めに明確にしておきましょう。
2. 構成を考える
どういう流れで伝えたいことを持っていくか、道筋を立てておきましょう。
この例では、いくつかツールの検証を挟んでいるのですが、検証する前にどの観点で評価するのかを読者と認識合わせをする必要があるため、理想を先に述べることを肝としています。
現状→理想→検討→検証→結果→まとめ（or 感想）
3. 章の中身を順不同で箇条書きする
全体の章構成が決まれば、次は章の中身の構成を考えます。
この時は、素材を集めるイメージで頭に浮かんでいる伝えたいことをとにかく箇条書きにします。
現状 - 見積もりと稼働の差分がわからない - タスク消化時間を全て可視化できてない - 分割したタスクの合計時間を計算しないといけない
4. 順不同の箇条書きを並び替える
素材が集まったら、伝える順番を意識して箇条書きを入れ替えましょう。
このタイミングで表現が欠けていないか（主語がない、修飾語がないなど）を確認し、整えておきます。
又、不要な文章やそこまで伝える必要がない内容は思い切って削除してしまうのもよいです。
現状 - 分割したタスクの合計時間を計算しないといけない - 見積もりと稼働の差分がわからない - タスク消化時間を全て可視化できてない
5. 箇条書きを文章化する
ここまできたら後は接続詞を使って文章にするだけです。
現在は分割したタスクの合計時間を手動で計算する必要がありますが、全てを算出できていません。 そのため、見積もりと稼働の差分を計ることもできず、ボトルネックがわからない状態です。
コンテンツ編
先に何をするかを伝えてから説明をはじめる
操作手順などを紹介する際はいきなり手順を説明するのではなく、何をするための手順かを先に説明しましょう。
読者の目線や理解を意識して、置いてけぼりにしないように意識しましょう。
もし、知っていることを前提に紹介する場合は、予め記事の先頭に対象読者を記載しておくとよいです。
強調したい箇所は太字にする
一段落につき、1つくらい太字にすると文章にメリハリができてよいです。
箇条書きと組み合わせて簡潔に表現する
手順など順を追って説明する場合、「~して」を繰り返すような文章は読みづらいです。 うまく箇条書きを取り入れて、簡潔に表現できるようにしてみましょう。先頭に数字を振っても良いかもしれません。
✕ 寝る時は、トイレ行って、電気消して、アラームセットして、ベッド入ります。
◯ 寝る時は以下の手順を行います。
- トイレへ行く
- 電気を消す
- アラームをセットする
- ベッドに入る
画像のみ連続で貼らない
GUI操作が多い説明だとやってしまいがちですが、デバイスによっては見づらくなってしまうこともあります。
もし、画像のみで完結させるのであれば、画像を編集して補足の情報を加えることをオススメします。 編集する際は、対象を囲むだけだと初めて見る人には既存のものと区別ができず、同化してしまう場合もあり気づきにくいので矢印などもつけるとよいです。
画像のトリミングをして無駄な余白やノイズを減らす
載せる画像に余白が多いと、スクロールの手間が掛かったり、スマホ表示時に見てもらいたい箇所が小さく写るという問題が起こりえます。一部のみを載せたい場合、不要な箇所はトリミングして重要な箇所のみフォーカスできるようにするとよいです。但し、切り取りすぎると対象箇所がわからなくなってしまうので適度な範囲で絞りましょう。
Markdown編
シンタックスハイライトを付ける
サービスやエディタの対応にも寄りますが、コードブロックにはシンタックスハイライトが付けれられる場合が多いです。
以下のコードでは役割ごとに色分けされて表示されていると思います（PCのみ）
class ApplicationController < ActionController::Base def hello render html: "hello, world!" end end
都度、言語を設定するのは面倒ですが、読みやすさが断然に変わるので全て付けるようにしましょう。
ソースコードを色付けして表示する（シンタックスハイライト） - はてなブログ ヘルプ
その他
文字校正を機械的にチェックする
textlintという拡張機能を使うとChrome上で文章がおかしくないかのチェックができます。 この拡張機能はMarkdownにも対応しているのでオススメです。
声に出して読み返す
大きな声を出す必要はありません。ぶつぶつと小声で良いので文章を口に出して読み返しましょう。
口に出すことで文章の言いまわしや接続語に違和感がないか確認することができます。
最後に
少し長くなりましたが、これらを事前に押さえておくことで少しでも執筆の手助けになれたらと思います。
個人で書いているうちはあまり言語化できないことなので、気づいた際に随時更新していく予定です。
直近では、インターンの寺田さんがこれを参考にして初ブログを書いてくれました。
エンジニアブログ編集部の振り返りは来年に書きたいと思います。
