自分が技術記事を書くモチベーションとか、気をつけていることとか

自分が技術記事を書くときのモチベーションや気をつけていることなどをまとめてみました。

💪 書くモチベーション

結局のところ、「書くのが好き」 というところが大きいのですが、それ以外にも書くモチベーションはあります。

他の人の記事に助けられているのでそのお礼に

自分も様々な困難にぶちあたったときに他のひとの記事に助けられています。だからこそ、自分の持っている知見もまた公表することで誰かの助けになるかもしれないと思い、記事を書いています。

頭の中の理解が深まる

文字通り知識を記事に言語化すると、より理解が深まります。普段分かっていてコードも書けるけれども、それを文章として起こすにはその知識を客観的に見る必要があります。記事を通じて自分の知識の棚卸しになります。

👉 書く時に気をつけていること

実際に記事を書く時に気をつけていたり、心がけていたりすることです。基本的には分かりやすい文章にするためのポイントです。

1. 間違った事実を書かない

当たり前ですが、用語の使い方であったり、機能の説明であったりに間違ったことを書かないように心がけています。特に自分の中で認識があいまいな点は必ず調べるようにしています。そのような調査でもまた理解の深化につながっています。

ただ、自身の記述が正しくないことについては許容しています。具体的には「display: flexは左から右へ横並びにするプロパティです」と言及したときに、この説明は誤っていませんが、必ずしも正しくはないです。flex-directionがcolumnのときは縦になりますし、アラビア語のような右から左へ読む言語であれば、向きが逆になります。正しくならない条件が説明において本筋でなければ正しくなくても許容します。関連するものであれば条件も含めて解説します。

あいまいな認識はあらためて調べて正しいかどうか確認します。そのような調査の過程で自分の理解が深まります。単語の意味や表現もできるだけ間違わないよう気をつけています。

2. 分かりやすい日本語を努める

分かりにくい日本語の文章を避けるように努めています。たとえば、主語と述語の関係が誤っている文のねじれを避ける、長すぎる文を分割する、修飾語のかかりかたを気をつける、といった文法上のテクニックです。そのほか、文末が同じになる（〜です。〜です。のような）と単調になりがちなのでうまく変えたりもします。

3. 暗黙的な前提や文脈を避ける

ある説明に対して前提となる条件や背景を必要とするとき、その前提の説明なし話を進めないよう注意しています。たとえば、いきなり「useEffectが〜」と始めてもReactを知らない人にはなんのことか分からないでしょう。Reactを知っていてもReactのことかと頭の中で切り替えが必要になります。そのような認知的負担を減らせるようにしています。

記事のタイトルでは、フロントエンドであることも明示的にすることもあります。クラス構文といったものはJavaScriptだけだなく、他の言語にもある機能です。JavaScriptの話であることを記事名に含めることで、他の言語の話だと勘違いしないようにしています。

4. 記事の冒頭が文字ばかりにならないようにする

記事の冒頭は読者の第一印象に関わる部分です。文字ばかりの記事だと重たい印象になってしまうので、導入部に画像やサンプルなどを配置してその印象を和らげるようにします。基本的には内容を説明する画像や図版にしますが、特になければイメージ画像みたいなものを使います。

5. 客観的な事実と主観的な意見を区別する

これもよく言われることですが、事実と意見を区別するよう意識しています。たとえば、アニメーション演出があるとき、「アニメーション終わるまで読めない」は事実で「うざい」は意見になります。事実と意見を混ぜると文章が胡散臭い文章になりがちです。

余談ですが、「断定系（いいきり）」表現の使い分けに事実と意見で分けています。事実は誰が見ても同じなはずなので断定にしています。意見については反論もあると思うので断定表現を避けています。

「先方は懸念を示していますが、この方針でふっしょくできると思います」
「先方は懸念をしていると思いますが、この方針でふっしょくできます」

この2文は言い切り系と推定系を比較する文章です。上の文章の方が信頼を感じると思います。聞き手は先方が懸念を示しているかどうかは推定ではなく事実であってほしいです。一方で方針については本当に妥当かどうかは分からないこともあります。下の文章は懸念が事実かどうか分からないのに、方針だけは断定されていて、本当にそうなのかなぁ、と感じさせてしまいます。

6. ネガティブな表現はできるだけ避ける

ある技術についてのネガティブな表現やいわゆるディスりは避けます。その意味で、比較記事みたいのは基本書かないです。

ただし、デメリットは書きます。さきの「事実と意見」の段落と関連しますが、デメリットはその特性が持つ事実であり、ネガティブ表現は意見です。「〇〇は使えない」はネガティブな意見ですが、「〇〇はその用途に向いていない」はデメリットの説明になるはずです。そこに客観性があるかが肝心です。

📝 技術記事を書く、ということ

技術記事を書く意義は主にナレッジの共有と自身の理解の深化があると思います。ちまたでは「技術記事を書こう」という声が聞かれますが、おそらくこれらのメリットを受けてのことだと思います。知識の共有や自分の理解を深めるのは良いことなので、その意見には賛同します。もちろん、情報の正確性などは発信者の責任なので誤った情報の発信などは気をつけたいものです。もし、自身がなければ公開せずに書くだけでも身になると思いますし、社内のような閉じたところでの共有から始めるのもアリだと思います。

一方で書くモチベーションをどう持っていくかは難しい問題です。個人的にオススメしたいのはモチベーションを外部に持たないことです。外部とは、いいね数や他人からの評価といった自分の外から与えられる価値です。モチベーションを外部に持つとそれが得られないと止まったり、それを求めることが目的になったりしてしまいます。

モチベーションを内部に持って、自分のために行う方が健康的に続けられると思います。記事を書こうと思っている人の参考になれば幸いです。