自分の技術記事の構成 & 読みやすさのための意識
きっかけ
気がついたら、Qiita に書いた記事の個数が 30個を超えていました。
何本か書いてきて、自分のいつもの記事構成が確立してきたので、それをここに記してみます。なんかの参考にでもなれば幸いです。
構成は主に 3つ + その他
全記事いつもこの通り･･･とはなっていないです。その時の内容や気分によって多少は変動します (でも大体似た感じではある)。
手順解説系
タイトル例: X で Y をする (したい, する方法 など)
- やりたいこと
- 用意するもの, 環境 など
- 手順
- まとめ (あれば)
トラブルシューティング系
タイトル例: X で Y ができないとき
- あらすじ, 背景 (あれば)
- 問題発生までの手順 & 問題の内容
- 解決方法
- 問題の原因
要点まとめ系
タイトル例: X の Y まとめ
- 概要
- 各項目を淡々と記載
- その他メモ, 補足事項
その他
書いたときの気分次第で、本当に構成と言えるものは無いのですが、大まかにはこのような流れです。
タイトル例: 決まった構成無し
- 背景
- 事例とかやったこととかを挙げていく
- 気づいたこと
- まとめ
意識していること
ゴールを早めに示す
「手順解説系: やりたいこと」「トラブルシューティング系: 解決方法」がゴールにあたります。
何の解説かがすぐわかって、探している情報かすぐ判断できる方が優しいだろう、という意図があります。
要点まとめ系やその他など、目立ったゴールが無い話は、概要を示してから内容を淡々と綴っていきます。
調べてすぐ出る話はカット
例えば Unity Asset のインポートだったら、インポートの手順はカットして「この Asset を入れてください (URL)」と書きます。
Asset インポート手順は調べれば出てきますし、人によっては解説不要でしょう。わざわざ書くのは手間ですし、記事が長くなって人によっては外乱にしかならないかもしれません。
※ ただし、本当に初心者向けの内容だったら、手取り足取りフル解説してあげた方がいいかもしれません。そこは対象読者によって判断します。
書きたいけど本題からちょっと離れる話は別枠へ
ちょっと Tips がある、けど本題にそこまで強く関係しない･･･なんてこともあります。例えば make の -j オプションとか (ちなみにこれは並列ジョブ数の指定)。
そういった話は、Zenn でいう :::message 枠で当該箇所の下、または補足や付録として記事の末尾に書きます。「要点まとめ系: その他メモ, 補足事項」に該当します。
内容がシンプルなら概要枠カット
概要を書いたとしても、記事タイトルのリピートしか書けないようならカットします。
例えば「ffmpeg だけで 動画→GIF アニメ変換する」みたいに、タイトル通りそのままな内容のときとか。
おわり
雑に思いついたことを記しました。意識していることは他にもいくつかある気がしますが、思い出して気が向いたときにでも追記しておきます。
Discussion