技術記事を書くための Tips
この記事は、takumma のやれるところまでやってみる１人 Advent Calendar 2022 20日目 および 鈴鹿高専 Advent Calendar 2022 20日目 の記事です。
はじめに
技術記事を書くのは大変です。記事を書くにはそれなりの労力が必要ですし、そもそも文章を書くということを苦手にしている人も多いのではないでしょうか。
しかし、技術記事を書くというのは良いアウトプットになると同時に、世の中に知見を共有することで自分や他の誰かの助けになったり、自分自身の文章を書く力を養うことにもつながったりと、さまざまな良い効果があります。
この記事では、技術記事を書くことに関する幾つかの tips をまとめていきます。
下書きを箇条書きする
文章を構成を考えるのには、それなりに頭を使います。技術記事を書こうとすると、記事に書く専門的な内容と文章の構成の２つ（言葉遣いやその他のことを考えればもっと！）を頭の中に置きながら書かなければなりません。そうすると、頭が混乱してなかなか書くのが進まなかったり、かけても構成が崩れたりして読みにくいものになってしまったりします。
２つのことを考えなければならないのならば、その二つを分離してみましょう！
記事を書き始める前に、記事にしたい内容を箇条書きで書き出します。箇条書きの階層構造は、そのまま見出しに変換すれば、それだけで記事の構成を作ることができます。一旦書きたいことを箇条書きにすることで、全体を俯瞰して構成を見直したり、内容の取捨選択をすることもできます。
あとはそれぞれの見出しの内容をより詳しく書いていったり、文章を見直したり、誤字を確認すれば、頭の中に置くことを適切に分離しながら記事を書くことができます。
記事のピースを集める
記事を書くのには、時間も労力も必要です。この時間に書くぞという時間を決めて、集中力を高めるためにカフェみたいな場所に行ったりして書く人もいるかもしれません。しかし、そのようなことをするためには体力を使いますし、計画し実行する強い意志が必要です。
時間と労力を分散するための良い方法があります！ それは、普段から記事のピースを作って集めておくという方法です。
気になった記事とか読んだ記事をまとめてコメントとか新たな知見を書き足したメモを作ったり、作業をしながら作業ログを残しておいたり、ふとした気づきをサッと文章にして残しておきます。そうすることで、ふとした時に見つけた知見を自分のために貯めておきつつも、記事を書くときになればそのピースを組み合わせたりすることで記事の土台を簡単に作ることができます。特にこの記事のような Tips をまとめたものを書く場合は、集めた記事のピースを適切な構成にしてまとめれば良いのでとっても有効です。
ピースをそのまま公開してしまうというのも一つの手です！Zenn のスクラップは小さなメモを集めてそのまま公開するのにとっても便利です。
特にこの記事のような tips をまとめたものを書く場合は、集めた記事のピースを適切な構成にしてまとめれば良いのでとっても有効です。
三文で改行する
記事を読む人が読みやすい文章にするためには、文の内容に合わせて適切に分けることが重要です。適切に分けることで、読む側が内容に合わせて頭の中を切り替えながら読むことを助けます。
文章を分ける１つの指標になるのが、「１つのまとまりに対して、３文までにする。」 ということです。３文というのは必ず守らなくてはいけない指標ではありませんが、３文程度にまとめて分けることで、グッと読みやすい文章になります。
また記事を書くあなたにとっても、読みやすい文章になることで文章の間違いを見つけやすくしたり、細かい文章構成を見直しやすくなるというメリットがあります。
アウトプットを変換する
積極的に活動しているあなたならば、技術記事以外のアウトプットを沢山持っているのではないでしょうか？
例えば、
- 作業ログ
- LT スライド
- 趣味で作ったツール
- 仲間との技術的な議論
などです。これらは、記事を書くための良い素材になります。
作業ログであれば、詰まったことを分かりやすく書き下して記事にすれば、同じように詰まる誰か（未来のあなたかもしれません）を助けることができるでしょう。
LT スライドなら、わかりやすく構成が既に組まれているので、その台本を記事の文章としてしまえば記事を簡単に書くことができます。スライドに図や絵を多用しているならば、スライドをそのまま画像にして記事に貼り付けることで、読む側の理解を助けることもできます。
趣味で作ったツールなどは、そのツールを作ったことを記事に書けば同じようにツールを作りたい人やツールを使いたいと思う人の興味を引き、そのツールの良い宣伝にも繋がります。
また仲間と行った技術的な議論は、そのことについて追加で調べてみると、公開されている他の人の議論を見つけることができたり、そこから新たな知見を得ることができます。それらを記事としてまとめれば、他の人がその情報・議論にたどり着く助けになります。
静的解析を行う
何かしらのコードを書く時、静的解析を導入するというのはコードの可読性を守る上で強力な助けになります。静的解析を人に任せるということがいかに危険であるかはプログラマなら誰しも理解できるでしょう。
自然言語で書かれた文章も同じです！ ツールの力を使うことで、文章のチェックを簡単に行いましょう。
textlint は文章の校正をするのにとても便利なツールです。VS Code の拡張機能を利用したり、CI の中に組み込むことで、文章の校正を簡単に行うことができます。
また少し手荒ですが、書いた文章を Word に貼り付けるというのも有効な手段です。Word の文章校正はとても優秀なので、Word に貼り付けることで誤字を見つけたり文章の誤りを見つけて修正することができます。
場所を選択する
技術記事を公開する場所はさまざまですが、適切に選択することによってより効果的に公開することができたり、技術記事を書くハードルを下げることもできます。
技術記事を公開する選択肢としては、例えば以下のようなものがあります。
- Qiita、Zenn、DevelopersIO などの技術記事プラットフォーム
- note、はてなブログ などのブログプラットフォーム
- HackMD、ScrapBox、Notion などのドキュメントツール
- 個人ブログ
Qiita や Zenn はエンジニアの多くが見ていて馴染みの深いサービスで、検索から「Qiita」という文字を見て流入してくる場合も多いため、技術記事を他の人に見てもらいやすくなります。記事の内容や対象読者によっては、note などの他のサービスを利用する方が読んでほしいユーザーが自分の記事に出会いやすくなるかもしれません。
一方で、そういったブログサービスに投稿して不特定多数の人に見られることが怖かったりハードルを感じる人も一定数いるでしょう。そのような人は、例えば HackMD や Notion などのドキュメントツールの公開機能を使って、ブログサービスに載せずに SNS に共有して簡易的に公開するという方法がいいかもしれません。この方法なら自分の周りの人を中心に公開できるので、見せたい人には見せつつもあまり公開しすぎないということができ、技術記事を公開する心理的なハードルを下げることもできます。
また、個人ブログのサイトを作ることで、自分が使いたい・書きたいと思う場所を作るという方法もあります。
最後に
何度も言いますが、技術記事を書くというのは大変な労力を消費します。しかし技術記事を書くことで、誰かの助けになったり、自分のやってきたことの記録やアウトプットになったりとさまざまなメリットがあります。技術記事というのは、技術を相互に高めていくことのできる非常に良い文化と言えるでしょう。
アドベントカレンダーはそんな文化を活性化するとても良いイベントです。もし身近なコミュニティがカレンダーを開いていたりしていれば、良いきっかけと思ってぜひ参加してみてはいかがでしょうか。
Discussion