ロコガイド テックブログ

「地域のくらしを、かしこく、たのしく」する、株式会社ロコガイドの社員がいろいろな記事を書いています。

「地域のくらしを、かしこく、たのしく」する、株式会社ロコガイドの社員がいろいろな記事を書いています。

テックブログの書き方

f:id:conceal-rs:20201130203525p:plain

こんにちは、16が楽しみで仕方がない小川@conceal_rsです。この記事はロコガイド Advent Calendar 2020の21日目です。

テックブログを書くのって大変ですよね。エンジニアはプログラムを書くのが得意ではあっても、文章を書くのが得意かどうかは人それぞれです。文章を書くのはわりと訓練が必要なことなので、長文を書いた経験が少ないと書くのに時間がかかってしまいます。たとえば毎日個人ブログ書くとか日記をつけるとか。 とはいえ今から練習していては間に合わないので、レビューするときに見ていることとか書くときのコツなどを紹介していきます。

ブログのアウトラインを書くとき

ブログを書くときにアウトラインを用意するのはいいことです。と言うかアウトラインも書かずにいきなり書き始められるなら、むしろ何もアドバイスすることはありません。

大枠を箇条書きで書く

ではアウトラインをどうやって書いていくかですが、まずは大枠を決めます。お話で言う起承転結の概要ですね。例えばこの「テックブログの書き方」だと、

- まずはブログのアウトラインを書いて
- 次に本文を書いて肉付けをしていき
- 次に何度か推敲していくと
- いい文章が出来上がる

こんな感じでしょうか。最初は短くても大丈夫です。むしろ長いと考えることが多くなるので、なるべく短くするのがよいですね。あとこの段階では詳細はどうでもいいのでざっくりでいきましょう。要点はこれを読んだだけで内容があらかたわかることです。なので、なるべく文章ぽくなっているといいですね。これが出来上がったらもう全体の90%は終わったようなものです、僕にとっては。

詳細を箇条書きで追加する

さて次はもう少し詳細を追加していきましょう。さっきのやつに子要素として追記していきます。

- まずはブログのアウトラインを書いて
  - 箇条書きで短く仕上げよう
    - ただし文章に流れがあるといいよね
    - そうすると内容わかるし
  - あとは思いつくまま詳細を追加しよう
- 次に本文を書いて肉付けをしていき
  - アウトラインを分解して、文章に情報を追加していきましょう
    - このときアウトラインの順番とかくずしてもOK
  - 項目ごとに文章を書いていこう
    - 前後の文脈はあとからそろえるので、その項目だけに注目でOK
  - 最後に接続詞を追加して、ブログにしていこう
    - まずは接続することに注力しましょう
    - 細かい点は推敲時に見直せば良いので、まずは仕上げていきましょう
- 次に何度か推敲していくと
  - ここがいちばん大事なポイントだよ!
  - できれば音読しようね
    - 音読すると、文章自体やその接続が不自然だと、唐突感とか違和感出るからわかるよ
  - 文言は統一しよう
    - 「ユーザー」と言ったり「利用者」と言ったりしない
- いい文章が出来上がる
  - 文体を統一しよう
    - 「ですます調」か「砕けた言い方」か「勢いアメリカン」かなど
  - 同じ接続詞は繰り返さない
    - 「また〜。」「また〜。」みたいになるとよくない
    - 特に同じ段落では繰り返さない
  - 言いたいことがまとまっているか確認
    - タイトルに言いたいことがあるとベスト
    - まとめにしかないと読まれない可能性がある
    - 序文にある程度詰め込もう

どうでしょうか。ここでもなるべく短めにすることをおすすめします。この段階であれこれ考えていると時間が足りなくなってくるのと、やはり要点だけに絞っておきたいというのが主な理由です。

また流れがあることも重要です。この段階で流れがない、つまり流れが途切れていると、あとで文章化するときに接続で困るんですよね。いきなり話が変わるときにどうつなぐのか、というのがブログを書いているときに一番難しいことなので、アウトラインの段階でそこを防ぐことを意識すると、あとの工数が短くなります。

それでも難しいとき

「箇条書きすら難しいぜ...」みたいな人は、ボイスメモを使ってつらつら思ったことを話してみるのもいいかもしれません。アイデアメモみたいな感じですね。書くのは大変でもしゃべるのはそこまでハードル高くないと思うので、こちらを試してみるのをおすすめします。

まとめ

さて、この段階になったらあとは書き上げるだけです。ここで文章ぽくなっていると、この次の本文を書くときに楽になるので頑張りましょう。要点は短文にすることです。短い文章って要点を整理しないと書けないので、アウトラインが長文になる人は要注意です。頑張って20文字以内の文章にまとめるようにしましょう。

ブログ本文を書き上げるとき

アウトラインができたら大体は終わりとはいえ、本文を書くのも難しいですよね。じゃあ何を考えながら書けばいいんでしょうか。

アウトラインを分解する

ここでもアウトラインを利用していきます。例えば先程書いたアウトラインのうち、最初の1ブロックを見てみます。

- まずはブログのアウトラインを書いて
  - 箇条書きで短く仕上げよう
    - ただ文章にして流れがあるといいよね
    - そうすると内容わかるし
  - あとは思いつくまま詳細を追加しよう

まずはこれを分解していきましょう。分解とは...という気持ちになる方もいるでしょうが、章立てを決める感じです。例えば上述の例だと、

## ブログのアウトラインを書く

### 箇条書きで書く

- 短く文章で書くとよい
- そのほうが流れがある
- そうすると内容わかる

### 詳細を追加していく

- 箇条書きに詳細を追加していく
- 要するに子要素を増やしていく
- ここでも流れが重要

こんな感じでしょうか。こうやると何となく書くことがわかってくる気がしますよね。気持ちが大事です。

まずは文章化する

それでは文章にしていきましょう。まずはいい文章を書くとか考えずに、口語でいいのでどんどん記述していきます。やり方としては、以下のような感じで進めるとよいでしょう。

  • 箇条書きを人に説明するときにどう喋るかを意識して書いていく
  • 文章自体がなにかの意見を言うものであれば、その反例があとに続くとなおよし
  • 修飾語とかいっぱいつかって、可能な限り長い文章を書いてみましょう
  • ただし口に出してみて違和感があるならやめときましょう

例えば上記の例ではこんな感じになります。

## ブログのアウトラインを書く

### 箇条書きで書く

- 箇条書きを書くときは短い文章で書いていきましょう。
- 箇条書きをつらつら書くことでなんとなく意味の流れができるはずです。
- そうするとその流れで読んでいくだけで意味がわかるような箇条書きができるはずです。

### 詳細を追加していく

- 次に箇条書きに詳細を追加していきましょう。
- 詳細とはつまり子要素を追加してくことです。
- ここでも流れを重視して書かないと、本文を書き始めるときに大変になるので注意しましょう。

どうでしょうか。ちょっとは読み物っぽくなったでしょうか。大事なのは読んでいてそれっぽくなっていることです。そこが難しいと言われそうですが、 喋って説明するとどうなるか を意識してすすめると良い感じになると思います。テックブログは解説書とか技術書ではなく、どちらかと言うと読み物という意味合いが強いので、スラスラ読める ≒ 喋って説明と言えるため、この手法がいいんじゃないかと思ってます。

文章を肉付けしていく

ここまでで大枠完成したので、次はいよいよ箇条書きを文章として肉付けしていきましょう。「肉付けってどうやってやっていくのか」という疑問があると思うので、簡単な手順を書いておきます。

  • 箇条書きを説明する、もしくは説明を補強するような理由、例え話、失敗事例、成功体験などを前後に挟む
  • 修飾語とか副詞、接続詞などを使って、長くしていく
  • 口語調に変換する

まずは順番にやってみましょう。とりあえず箇条書きの前後に説明などを追加していきます。

### 箇条書きで書く

- 箇条書きを書くときは短い文章で書いていきましょう。
  - 長い文章で書くのも悪くはないんですが、論点が散らばってしまうため、あまり得策ではありません。
  - 短い文章で簡潔に書くことで、後から見返しても意味のブレがなくなるためおすすめです。
- 箇条書きをつらつら書くことでなんとなく意味の流れができるはずです。
  - ここで流れがないと何が問題になるかと言うと、話の接続が不自然になることです。
  - じゃあ不自然になると何が問題かと言うと、最後に文章化するときに「接続詞」に悩むことになります。
- そうするとその流れで読んでいくだけで意味がわかるような箇条書きができるはずです。
  - ここが難しいという方はアウトラインを喋りながら書くというのをしてみるといいかも。
  - なれない方はボイスメモ用意してやるとなおいいかもしれません。

ここでもこれまでと同様に、喋って説明するとどうなるかを意識しながら書いていくといいでしょう。文章化した箇条書きを補足するようなことを追加していくだけで、さらにそれっぽくなってきました。これだけでも上から読んでいって読み物っぽくなっていれば成功です。ではいよいよ箇条書きから脱出していきましょう。

本文にしていく

最後は接続詞などで文章にしていくだけです。やってみるとこんな感じでしょうか。

アウトラインですが、まずは箇条書きで書いていきましょう。とは言えどうやって箇条書きで書いていけばいいんでしょうか。まずはそのコツをつらつらと書いてみたいと思います。

### アウトラインの箇条書きの仕方

箇条書きというぐらいなので、短い文章で書いていきましょう。
長い文章で書くのも悪くはないんですが、論点が散らばってしまうため、あまり得策ではありません。
短い文章で簡潔に書くことで、後から見返しても意味のブレがなくなるためおすすめです。

また箇条書きを書くときには流れが重要になってきます。
つらつら書くことで流れができている状態になるのがいいのですが、なかなか難しいかもしれません。
ただここがうまくいかないと、あとで文章をつなげるときに悩みが深くなるので、
この段階でちょっと頑張ってみてください。

どうでしょうか、流れがあるような箇条書きができたでしょうか。
ここが難しいという方はアウトラインを喋りながら書くというのをしてみるといいかもしれません。
例えばスマホのボイスメモを用意して喋る内容を記録し、それを書き起こすなどは方法の一つですね。

どうでしょうか、それっぽい感じになっていますね。

まとめ

ここではアウトラインから文章にする方法をまとめてみました。大事なことは喋って説明するとどうなるかということです。何も論文を書いているわけではないので、肩肘張らずに喋った内容を書くぐらいの気持ちで書いてもらえると、もう少し書きやすくなるのではないでしょうか。

推敲はどうやってやる?

文章化できたらそれで終わりかと言うと、まだまだ始まったばかりです。いちばん大事なのは推敲と言っても過言ではありません。この最後の詰めのプロセスをしっかりやることで、文章としての完成度が上がり、より人に読んでもらいやすいブログ記事となります。次はこの推敲・構成をどうするかを説明していきましょう。

まずは音読しよう

これを意外にやらない人が多いんですが、自分の書いた文章を声に出して読んでみましょう。上から順に飛ばすことなく読んでいくと、うまく文章がつながっていないところや論点が急に変わっているところなどが気になってきます。この気になったところを重点的に修正していくことで、よい文章になっていきます。

特に「コンテキストをわかっていない人が、この喋ってる内容を聞いてちゃんとわかってもらえるかどうか」を意識しながら音読するとなお効果的です。技術的なことはともかく、背景や経緯などについてスポッと抜けてしまう場合は多々あります。テックブログは広くいろいろな人に読んでもらいたいので、この点についてはなるべくわかりやすく書けているかを確認していきましょう。

他人の目を入れる

個人ブログだとやらないことの1つがこのピアレビューではないでしょうか。弊社では互いの記事をレビューし合っているため、読みやすい文章になっているのではないかと思っています。音読の場合と同じように、コンテキストを知らなくても大丈夫かなど、いろいろな観点で指摘してもらって、より良い文章を目指しましょう。

textlint を使ってみる

Ruby や TypeScript も Rubocop や Eslint などを使って校正するので、日本語も同様にやってみましょう。例えば textlint を使ってある程度自動的に修正できるところは修正していくとよいでしょう。

まとめ

これ以外にもいろいろとやり方はあると思いますが、ここで紹介した内容を元に、いろいろと推敲をしてみてはいかがでしょうか。個人的には音読推しなので、わからなければひたすら音読するのがいいと思ってます。

いい文章の書き方

最後にいい文章を書くコツなんかをまとめておきたいと思います。

文体を統一しよう

いい文章という意味で最も大事なのは文体の統一です。これが中途半端だと読んでて脳内に「?」が灯り続けます。「ですます調」で統一するのか、「〜である、〜だ」で統一するのか、自分の好みでいいので統一してみてください。ここでも重要なのは喋って違和感がないかです。音読してみて違和感があるのって文体のことが一番多いんですよね。急に変わったりすると「書いてる人変わったのかな?」みたいな気持ちになります。この点は注意してみましょう。

同じ接続詞を繰り返さない

これはどういうことかというと、例えば以下の文章はどう感じるでしょうか。

私はAのことがよいと思いました。
またBのこともよいと思いました。
またCのことも良いと思いました。

「言いたいことはわかるがもうちょっといい言い方があるだろう」という気持ちになります。これを例えば、

私はAのことがよいと思いました。
またBのこともよいと思いました。
そしてCのことも良いと思いました。

このようにするとどうでしょうか。ちょっとですが、受ける印象が変わったのではないでしょうか。なんというか流れがある感じです。ただこの言い方であれば、

私はAのことがよいと思ったんです。あとBもいいし、Cもいいと思って。

としたほうがなんとなくいい文章ぽいですよね。なので同じ接続詞が繰り返されているときには、文章そのものをちょっと見直すといいかもしれません。

言いたいことがまとまっているかを確認する

やはり重要なのが、言いたいことが言えているか。一番いいのはタイトルにすべてが込められていることです。とは言えネタバレになるのが嫌というもあるので、内容次第ということはあります。一方でタイトルに興味を惹かれないと読まれもしなくなってしまうので、概要とか結論とかがタイトルにあるのは有利に働きます。

あとは序文に言いたいことを言うパターンです。よくある3行まとめですね。意外かもしれませんが、結論を先に書いてあとからその説明をするのは、実は読みやすいパターンなんですよね。特にブログが中規模以上の長文になる場合には、最後に結論を書いてしまうと読まれない可能性が高くなってしまいます。そうならないためにも、最初に言いたいことを言ってしまってから説明するやりかたも考えてみるといいでしょう。

全体のまとめ

いろいろと書いてきましたがいかがでしたでしょうか。一番重要なのは喋ってみることです。意外にこれをやってない人が多いので、まずはこれに取り組んでみましょう。アウトラインでも本文でも推敲でも校正でも、どんなときでも同じです。まずは喋ってみて違和感がないかを意識しながら、みなさんもテックブログを書いていきましょう!