私の技術記事の書き方

技術記事を書くことは、最初はなかなかハードルの高い作業に思えます。文章を書くにはある程度の慣れが必要である考えています。

誰しも初めのうちはうまく文章を書くことができず、文章を書く訓練を重ねることで、内容を伝えやすい・理解しやすいある種の「型」を発見されているのではないかと思っています。

この記事では id:azukiazusa が普段記事を書く時に考えていることを書き下していきます。

見出しを先に書く

私が技術記事を書くときには最初に見出しから書き始めます。下記のような感じです。

記事の下書き画面。本文には「## 見出しを先に書く ## コードは実行可能にする ## おわりに ## 参考」と見出しだけが書かれている。

見出しを先に書くことで、文章全体の構成を把握できます。アウトラインから書くというやつですね。

アウトラインを作らずに記事を書いていくと、文章全体で伝えたい内容がぶれてきてしまうことがあります。初めに大まかな構成を頭の中で練っておき、忘れないうちに何を書きたいのか見出し化しておくようにしています。

見出しを書き終えたらその内容に従って細かな文章を組み立てていきます。記事をいきなり全部書こうとするのは難しいので、見出しごと小さなステップで進めていくことが大切です。

記事全体の構成は以下のような感じになります。論文で言うところの序論・本論・結論と近い構成となってます。

  1. はじめに
  2. 本文
  3. おわりに
  4. 参考

「はじめに」は文字通り記事の冒頭に書かれる文章です。ここの内容はなぜこの記事を書いたのか、どのような課題があるのかを端的に記述します。序論に該当する箇所ですね。

ここに筆者の自己紹介が書かれていることも多いですが、大抵の技術記事を投稿するサイトでは筆者のプロフィールは他の箇所から参照できるようになっています。基本的には記事の内容とは関係のない補足事項のような情報はあまり書かないようにしています。

「本文」は本論に該当する箇所です。先に述べた見出しが入るところですね。

「おわりに」（あるいは「まとめ」）では記事の本文中で述べた内容を簡潔に要約します。この部分だけ読んでも何を伝えたかったかわかるようにしておくと良いですね。

また、記事の最初の方に書いた内容はおわりまで来たときには忘れられていることも多いので、改めて思い出してもらうという役割もあります。

「参考」には記事を書く時に参考にした記事のリンクをリスト形式で記載します。技術記事を書く際にはなにかしらの調べごとをしているはずです。記事を見たタイミングでリンクをコピーしておくと、忘れることもないので良いでしょう。

一般的なマナーとして参考文献は載せておくべきですが、副次的な効果として後から自分が見返す時に何を元に書いたのかわかるので重宝します。

コードは実行可能にする

コードは実行可能にする、とは読者が記事中のコードを写経して実行できる状態を示します。記憶に定着させるために、写経をしながら記事を読み進める方も多くいらっしゃるかと思います（私もその1人です）。写経したコードが実行できないとなると、その時点で記事を読むことをやめられてしまう恐れが高いです。

コードを実行可能にするという目的を達成するために、以下の観点に気をつけています。

  • 文法エラーがないように
  • 文脈依存にならないように
  • foo ã‚„ bar のような名前を使いすぎない

文法エラーがないように

文法エラーがあるコードは当然実行できません。とくに初学者とっては記事の内容が悪いのか、自分の書き方が悪いのか判断がつかないことがありまので、結果として読者の時間を大きく奪ってしまいます。

記事の編集画面に直接コードを書くと、文法エラーが存在していても警告してくれません。 VSCode などのエディタに書いてからペーストするようにしています。

また、実際に実行して想定した結果が得られるか確認するとよいでしょう。

文脈依存にならないように

自分がコードを書いているときには、ソースコードの全体像がわかっているのでコードの断片だけ見ても全体の中でどのような役割を果たしているのかわかるものです。

しかし、記事の中でいきなりコードの一部分が出てくるとなぜそのコードが出てきて、何をするものか分かりづらいものです。前提となる文脈があるならば、その部分も説明されているとよいでしょう。

依存しているコードが記事の本旨と関係ないものであれば、その箇所は折りたたんで表示できるようにしたり、コードの全体像を GitHub のレポジトリに載せておくのもよいでしょう。例えば、以下のように未知のコードが import されていたりするとそのコードは実行できなくなってしまいます。

import { useUsers } from './useUsers';

export const UserList = () => {
  // この useUsers の内容はどこ？
  const { users, loading } = useUsers();

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
};

また、1つのファイルの中でコードの内容が過度に省略されていると、対象のコードをどのように書けばいいのか分かりづらくなってしまいます。例えば1度コードの全体を記載した後に、その内容に変更を加えるようなコードを書く時によく発生します。コードを変更した部分だけ切り出して書くと、その変更はどこに記述すればよいのか不明瞭になることが多いです。

// このコードはどこに書けばいいの？
<UserItem key={user.id} user={user} />

このような場合にはコードを変更した箇所の前後数行程度載せ、diff 記法で書くと変更箇所がわかりやすくなります。

  import { useUsers } from './useUsers';
+ import { UserItem } from './UserItem';

// 省略...

    return (
      <ul>
        {users.map((user) => (
-         <li key={user.id}>{user.name}</li>
+         <UserItem key={user.id} user={user} />
        ))}
      </ul>
    );

foo や bar のような名前を使いすぎない

foo や bar とはあるコード例を出す時に変数や関数名に特に意味のないことを示すために使われるものです。例えば、TypeScript の型注釈を説明するコード内で以下のように書かれたりしています。

// 関数の戻り値の型は引数の後に `:` でアノテーションします
const foo = (): string => {
  return 'bar'
}

私はこのような意味のない名前を使うことはできる限り控え、実際に近いコード例を書くようにしています。なぜなら、記事中にコードブロックが出てくるときは具体例を示すことが目的だからです。

言語の文法やコードの設計を説明する際には抽象的な論理だけ並べるのではなく、説得力を上げるために具体例も同時に記述されるはずです。その際に使われるのがコードブロックです。

foo や bar のような名前には具体性がありません。実際に使われるコードにはこのような名前は使われないからです。

foo や bar の名前は何か技術的な提案し議論をしてもらいたい際に、些細な物事に注力してほしくないような場面で価値があります。

記事は1日寝かせる

記事を書き上げたらすぐに公開したい気持ちになりますが、ここでぐっとこらえましょう。必ず書いた文章はひと通り見直しをします。例えば、1つの文が長くなりすぎていないか、表記ゆれがないかどうか細かい箇所を見直すだけでも文章全体が読みやすくなったりします。

ここで重要なのは、客観的第三者の視点で評価することです。記事を書いているときには、自分の頭の中だけにある前提知識を元に書かれていたりします。客観的に評価することで、他人から見て理解しづらい部分をよりよい表現に変えることができます。

第三者の視点で評価するには、1日寝かせて冷静になった頭で見直しをするとよいでしょう。1日寝ると記事を書いている時の記憶は薄れてくるので、記事を書いた人とは他人の気分になれます。

その他文法的な事項

その他、記事を書く際に注意している細かな文法事項です。文章全体の読みやすさに大きく関係するものではないですが、自分へのルールという気持ちでやっています。

  • 見出しは ## から始める
  • インラインコードブロックは装飾目的で使わない
  • 英語と日本語の間に半角スペースを空ける

見出しは ## から始める

文中の見出しは ## （つまり <h2>）から始めるようにしています。また、見出しレベルは飛ばさないようにします。

これは技術記事の文法上のルールというよりは、HTML の見出しのルールに近いですね。<h2> から始めるのはタイトルが <h1> タグであるはずだからです。

インラインコードブロックは装飾目的で使わない

インラインコードを使用すると、背景色が変更されて強調されたような見た目になります。（React のように）

ですが、強調させる目的で使用するの意味的には誤っています。HTML の <code> 要素は、コンピューターコードの短い断片の文字列であると識別できるような外見のコンテンツを表示します。

https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element

また、Google Chrome の翻訳機能は <code> タグの中身を翻訳しないようになっています。装飾目的でインラインコードを使っていると、内容が正しく翻訳されない恐れがあります。

英語と日本語の間に半角スペースを空ける

英語と日本語の間に半角スペースを空けると読みやすい...と言われている(?)ようですが真偽は不明です。このルールに関してはもはや癖になってるので、特に意識しないでやっていますね。

おわりに

以上、私が技術記事を書いている時に考えていることを言葉にしてみました。特に、先に見出しを書いてアウトラインから考えることや、隠された前提をなくして誰が見ても分かりやすくなることを重要視しています。技術記事を書く際に考えることは様々ではありますが、少しでも参考になると幸いです。

参考