おことわり
天久保 Advent Calendar 2022 3日目の記事です．『天久保』がどのような団体かよくわかっていないですが，なんか縁があったのでこの記事を書いています．
まとめ
自分が記事を書くときに意識していることは
- 記事の構成を考える
- 脚注を必要以上に使わない
- 最初に伝えたいことを全部書く
- 読み手にとっての「読みやすさ」を意識する
- コード内の細かな箇所に気を配る（ソフトタブ/ハードタブ）
- スマホでプレビューする
- 読み手が記事に参加できるようにする
です．
背景
12月といえばアドカレですね．ソフトウェアエンジニア/CS専攻の学生などの中には「12月は技術記事をたくさん書くよー」という方も多いのではないでしょうか．かくいう自分も何本かの記事を書く機会がありました．（以下サンプル）
が，自分は今まで技術記事をあまり書いてこなかったので，「なんかうまく書けないなぁ」「書いてみたはいいけど読みにくいなぁ」ということが多々ありました．
そこで，今回は自分が技術記事を書くときに意識していることをまとめてみます．自戒の意味も込めて書いている部分もありますが，少しでも皆さんの参考になれば幸いです．皆さんも意識していることがあれば，ぜひコメントで教えてください！！
1. 記事の構成を考える
1-1. 脚注1を必要以上に使わない
脚注，便利ですよね．ちょっと細かいことを補足する際，本筋と関係ないけど伝えたいことなどを書くときに便利です．自分もよく使っていて，特にLaTeX2でレポートを書くときは脚注を使うことが多いです．
しかし，技術記事を書くときに脚注を使うと，記事を読むときに「脚注を読むのがめんどうだなぁ」3と思ってしまうことがあります．というのも技術記事の特性上，脚注を読むためには，記事の最下部までスクロールしなければならないからです．LaTeXのように各ページごとに脚注を書くことができる場合はそこまで問題にはなりません4が，シングルページで構成されることが多い技術記事の場合は，これはかなりめんどうです．5
ということなので，自分は極力脚注を使わず，代わりに （） で囲んで補足を書くようにしています．これはこれで便利なのですが，多用しすぎるとまた文章が読みにくくなってしまうので，ほどほどに使うようにしています（とは言ったものの（）が多くなってしまうことが多々あります．こんな風に）．
ちなみに，このセクションは脚注を多用してみましたがどうだったでしょうか6．感想教えてください．
1-2. 最初に「まとめ」や「概要」を書く
自分は技術記事を書くときに，最初に「まとめ」や「概要」を書くようにしています．（これは学術論文から得た発想です）この構成は非常に気に入っています．
読み手にとってみれば，「まとめ」や「概要」を読んで，記事の内容がどんなものかをざっと把握できるので，記事を読む前に「この記事は読む価値があるかな？」という判断ができます（学術論文における概要の役割と同じだと思います）．また記事の内容をざっと把握できるので，読み手は記事の内容を把握しながら読むことができます．
また書く側にとっても，記事で伝えたいことを最初に明記しておくことで，伝えたいことがブレにくくなります．自分は好き勝手に殴り書きする癖があるので，この構成を意識することで文章が読みにくくなることを防いでいます．
2. 読み手にとっての 「読みさすさ」を意識する
2-1. コードブロックの書き方
技術記事なので当然コードを添付することが多いと思います．添付する際にはもちろんコードブロックを使っている方が多いと思います．
コードブロックとは，このようにコードを囲んで表示することです．
これは自分が思っていることなのですが，とにかく読むときには 画面スクロールをしたくない という気持ちが強いです．（ただ怠惰なだけかもしれませんが）
（言語にもよるのですが）例えば {} でブロックを作る言語などはちょっと深いブロックを作ると簡単に横に長くなってしまいます．（C言語でのサンプル，コードに意味はないです）
#include <stdio.h>
typedef struct {
int math_score;
int english_score;
} Point;
int main(int argc, char const *argv[]) {
Point sample_score = {1, 2};
for (int i = 0; i < 10; i++) {
printf("%d %d, ", sample_score.math_score, sample_score.english_score);
}
return 0;
}
例えば上のコードであれば，
- そもそも変数名が長い
- さらにifやループが絡むともっと横に長くなりかねない
ので，変数名を短くする，ロジックを簡潔にするあたりの対策をとって可読性をあげておくと良いと思います．その他にも，{ で改行しないなど色々ありますが，これ以上言うと宗教戦争になりそうなのでやめておきます．
その他にもソフトタブ/ハードタブの違いなど，コードブロックを書く際にはいろいろ注意が必要です．Go言語なんかだとこの差は特に顕著です．Goは基本的にハードタブを使うのですが，これをそのままプレビューさせると，ソフトタブよりも幅が広く表示されてしまうことが多いです．
【追記】Qiitaだとソフトタブ，ハードタブでの見え方に差はありませんでした．しかし，他の同様のサービスでは見え方に差があることも多いので，サービスに応じて使い分けてください．
【ハードタブ】
package main
func main() {
println("Hello, World!")
}
【ソフトタブ】
package main
func main() {
println("Hello, World!")
}
本質的ではないソフトタブ/ハードタブの差だけで，横方向へのスクロールが発生してしまうので，これは回避したいです．
2-2. スマホでプレビューする
皆さんは，今この記事をどんな端末で読んでいますか？もしかしたら，帰り道の電車の中で読んでいるかもしれません．一方で，記事を書くときは，ほとんどの場合でPCで書いていると思います．
PCで書いたものをそのままエイヨっと投稿すると，スマホで見たときには思っていたのと違う表示になってしまうことがあります．Web開発なんかだとこの差は当然意識することではあるのですが，技術記事を書くときにも，スマホで見たときにはどうなるかを意識することは大切だと思っています．ありがたいことにQiitaには「限定公開機能」たるものがあるので，PCで書いた記事を限定公開にしておいて，あとでスマホで確認してそのまま公開するという運用で自分はやっています．
3. 読み手が記事に参加できるようにする
自分が記事を書くときには，読み手が記事に参加できるようにしたいと思っています．この考え方は 無職やめ太郎さん（@Yametaro）の記事 高卒30代未経験からモダン・フロントエンドエンジニアになった軌跡を全て書いていく 内の発想を参考にしています．
背景を伝える
記事を書くときには，読み手に対して「なぜこの記事を書くことになったのか」を伝えることが大切だと思っています．これを明記しておくことで，同じ境遇の方に読んでもらいやすくなると思っています．そのため，記事の冒頭には，「〇〇に参加したので・・・」であったり，「〇〇をしたときに・・・」といった背景を伝えるようにしています．
コメントしてほしいことを明記する
（コメント欄が用意されているプラットフォームに投稿する場合）「〇〇についてコメントで教えてください！」といったように，コメントしてほしいことをある程度明記するようにしています．そうすることで自分にとっても，記事を読んだ方にとっても コメント欄からも新たな知識を得ることができる ようになりやすいと思っています．さらに読み手の方にとっても知識をアウトプットする機会を提供することもでき，マジでみんな幸せになれると思っています（伝われ）．
まとめ
以上が自分が記事を書くときに意識していることです．改めて書いてみると，思った以上に意識していることがあったなぁと思いました．と同時に記事を書く難しさを再認識しました．
技術記事を書くのは非常に面白いので，皆さんもぜひ記事を書いてみてください！！