@kaiba です。 自転車通勤を 2 年ほど続けて痩せ始めたのですが、オフィスが恵比寿に移転してから、ランチを愉しみすぎて太り始めました。 dev のことを「デブ」と書く人がいて、その度にビクついております。 辛くなってきたので ChatBot に指摘してもらうようにしました…。
今回は「技術記事の書き方」というテーマで書かせていただきます
僕は若い時、「日本語より Java が得意な kaiba.java」などと揶揄されてきた経験があり、今も自信があるわけではありません。 そんな心情ではありますが「アウトプットを多くの人に見てもらいたい」という気持ちで、積極的にアウトプットを心がけています。 僕のアウトプットには例えば以下があります。
- 自分のブログ(チラシの裏っぽさ半端ないのでリンクは割愛)
- Qiita
- GitHub
- 技術書典での頒布
- ソフトウェアデザイン
- 勉強会での登壇、開催
TL;DR
- 何のために書くかはっきりしよう
- どんな人が読むのか考えよう
- 文章構成を考えてから書こう
- 統一感のある文章を心がけよう
- 短く端的に書こう
例: スペースエージェントのテックブログ書いてくぞ!
今回は例として「スペースエージェントのテックブログ」を書くことを例にします。 よし!テーマを決めて、バリバリと書くだけです!
…がちょっと立ち止まって考えてみる必要があります。
何のために書くんだっけ?
会社のテックブログを書くとして、何のために書くのかを考えます。
- 単純にスペースエージェントを知ってほしい(知名度向上)
- スペースエージェントに興味を持ってもらい採用につなげたい(切実です!)
- 業務で躓いた点を公開して困ってる人の助けになりたい
企業のテックブログであれば「言わないでもわかるでしょ」という項目ばかりですが、 意外とここがぶれてしまうことがあります。 ぶれてしまうとモチベーションの低下に繋がり、やがてブログは過疎化します。 ここは執筆者を集めて打ち合わせして、合意しておくことが大切です。 あとから来た人のために、議事録なりドキュメントなりにしておくことも重要です。
誰が読むんだっけ?
文章は人に読んでもらうためにあります。 誰も読まない文章は書く意味がありません。
- 会社に興味がある人
- 技術的に困っていることがあり、Google などの検索エンジンからたどり着いた
この辺でしょうか。 ここがぶれるとライター、レビュアー共に辛い思いをするのでとても重要です。 例えば、問題になるのは以下のようなケースです。
- 何を書けばいいのかわからないけど、書けって言われたから書いてみる
- 自分のメモです。誰が読むかとか知りません
個人ブログならこれでもいいんですけど、今回は個人ブログではありません。 僕も「何が伝えたいのかわからない」「個人ブログみたいだ」、と散々叱られてきましたが、 当時はこの観点が欠如していました。 上司から言われたから書いており、誰のために何のために書いてるのか、全く理解していませんでした。
文章構成を考える
プログラムを書く時は、仕様を明確にしてからコーディングを始めますよね?(そうでない方は考えを改めるべきです!) 文章も同様に何を書くか決め、レビュアーと合意してから書き始めると以下の効果が得られます。
- レビュアーからの大どんでん返しがなくなり、お互い幸せ
- 不安感、ストレスなく、書き始めることができる
- 書くことがだいたい決まってるのですんなり書ける
例えば、みなさんが読んでいる記事の文章構成は当初以下のように考えていました。
# 技術的な文章の書き方
## 目的
- 弊社を知ってもらう
- 採用の際に参考にしてもらう
## 対象読者
- 技術文章がうまく書けず苦労している人
以下記事本文。
---
## はじめに
- 挨拶と導入
## 何のために書くんだっけ? 誰が読むんだっけ?
## 文章構成を考える
## 文章を書いていく
- 短く端的に
- 統一感
## まとめ
書いているうちに構成を変えたくなることはありますので、 「だいたいこんな感じ」で良く、後から構成を変えても良いでしょう。
僕は考えがまとまらないときや、嫌な予感を感じた時は、今でもこの手順を踏んでいます。
文章を書いていく
あとは書いていくだけ! ですが技術文章はちょっと特殊です。
書き手と読み手で持っている情報に差が出ないように前提情報を提供する
その文章を読む人は、初学者でしょうか? 習熟者でしょうか? 習熟者向けの記事の場合、思い切って初学者を対象にしないのもありですが、 事前に必要な情報が提供できるとカバーできることもあります。
短く端的に
例えばあなたが以下のケースに遭遇したときどう感じますか?
- 技術的に困っていることがあり、検索してたどり着いたところ、とても長い文章の記事がでてきた
- 余計な情報が混じっていて読みづらい
- 新しいプロジェクトに参加したとき、膨大な量のドキュメントを渡された
どちらも必要であれば仕方ないのですが、膨大な文章を読むのはとてもつらいものです。 とくにブログは通勤時などに流し読みされがちで、つまらなかったすぐ閉じられてしまいます。 目的が伝わるなら写真 1 枚と 1 文でも十二分ですし、それはすごく良い記事です。
技術文章は対象読者に対して必要最低限を心がけるべきです。 また、写真や図は文章より情報量が多く、わかりやすいものが作れます。 効果的に使っていきましょう。
統一感
例えば、プログラムで以下のようなものを見たら、気になりませんか?
- 大文字、小文字、キャメルケース、スネークケースの規則がめちゃくちゃ
- 同じ処理がコピペされていて無駄に行数が多い
- 同じことをしてるのに違う書き方をする
文章も同じです。 同一文章で「スペースエージェント」「SpaceAgent」「SPACE AGENT」と異なる表記をされると、 この表記の意味はなんだろうかと意識が途切れ、読む気がだんだんと無くなってくるものです。
幸いこの辺のことは「ド根性で頑張れ!」という時代ではなく、大抵機械的にチェックできます。 このブログは textlint が設定されており、機械的に統一感のある文章にできます。 本ブログの textlint 設定については別途共有できれば…。
まとめ
- 目的と対象読者を明確にしておき、その人達に向けて書く
- 不安な時は全部書く前に構成を考えて合意を取ろう
- 短く端的に、写真や図を効果的に
- 統一感大事
社内文章として書こうと思ったものなのですが、折角なのでテックブログに書いてみました。 外に出せる情報は積極的に出していきたいものです。