何の記事？

この記事はぐらだけアドカレ2023、5日目の記事です。

アドカレ記事を書くにあたって、記事を書くテンプレートを用意しました。

誰むけ？

これから技術記事を書いてみたい人
今後アドカレを書いてみようと考えている人
ガチガチの技術記事は書かない人
記事構成を固定化することで、執筆のストレスを減らしたい人

普段技術記事を書かない人が記事を書く場合か、逆に普段技術記事を読まない人に読んでもらうことを想定したテンプレートを意識しました。
わたしは決してわかりやすい文章の書き方を説ける専門家ではありません。
だからこそ、このゆるっとテンプレートが誰かの参考になることもあるかもしれない、と思い記事にしました。

参考にしたサイトなど

技術記事の書き方やQiita記事の書き方を検索しました。

ミノ駆動さんの記事

一番最初に文章の書き方について考えたのがミノ駆動さんのこの記事でした。
基本の骨組みはこの記事を参考にしています。
今また読み直しても色々と考えさせられるところがあります。

チェリー本の人の記事

伊藤淳一さんのブログやQiita記事を定期的に読んでいます。
などの記事も読みやすいのですが、命名規則やコードの書き方や考え方などは記事の書き方にも通ずるところがあるように感じました。

結城先生の本

理数系や数学の文章を書く人でなくても、文章を書く人を助けてくれる一冊です。
わかりにくい文章と、何故わかりにくいのか、どう改良するといいのか……を少しずつ読み解ける一冊です。

完成したテンプレート内容

2023アドカレ時テンプレート

# 何これ？
- トップ画像や一文など、端的に何の記事かわかるもの
- ひとこと感想
# 何の記事？
- ページに来てくれた人が「このページを読むことで得られるもの」がわかるような端的な説明
# 誰向け？ どんな役にたつ？
- 推定読者が誰かを書く
- 自分向けじゃないな、と判断した人が迷わずブラウザバックできるように
# あらすじ
- あらすじを好きに書く
- あまり長くなりすぎないように
# 具体的に何を使ったか
- 使ったツールをリンクや画像付きで紹介
- 参考サイトなどもここに載せる
- 見出し4くらいの大きさで、目次に載るようにする
# 何をやったか
- やったことを手順通りに書く
- 手順の番号を手入力し、見出し機能で目次に載るようにする。
# 結果
- 成果物や結果などを書く
- 感想などもここに書いていい
# 応用事例
- 他にも使えそうな事例ややってみたいことがあれば書く
- これも見出し機能で目次に載るようにする
# デメリット、できなかったことなど
- この手法ではできないことなど
- この手法を選ぶ前にやろうとしてできなかったことなど
- 同じ轍を踏む人が出ないようにという情報を残す

意識したこと

上記リンクから自分ならこれが必要と思う項目を抜き出してテンプレートをつくりました。
最低限この順番なら記事になり、どんな記事でも応用でき、ざっくり読み飛ばせそう！……を意識。

Qiitaは目次がデフォルトでつき、必要に応じて読み飛ばしができることが魅力だと思います。
なので、大切な項目は見出し機能を使って目次に並べることを忘れないようにというところも意識しました。

下記文章を各記事を書き出す前にコピーし、そこから箇条書きなどで文章を組み立てていきました。

結果

自分でも書きやすくなった
テンプレートがあることで落ち着いてかけるようになった
読む人を意識しながら文章を書くようになった

とはいえ、テンプレートができたところで読みやすい記事を書けるようになったわけでも、書き続けられるわけでもありません。
書き続けているうちに少しずつ変化していくものとも思います。
結城先生の本にあるように、著者の帽子を捨て、読者目線で改良していければと思います。