技術記事の装飾は、読者が説明と実行対象を区別するために使います。すべての段落へマーカーを付けると、重要な条件や操作が目立ちにくくなります。
ルールは同じ意味の要素に同じ装飾を使うことです。変数やファイル名、実行するコード、注意事項を分け、見た目を変えるために本文の構造を崩さないようにします。
文章、語句、コードの使い分け
SWELL公式はインラインコードに加え、FILEやDIRの表示、注釈などを案内しています。どの機能を使うかは実際の編集画面とバージョンで確認し、装飾の種類を増やす前に使う意味を決めます。
| 対象 | 表示の選び方 | 確認すること |
|---|---|---|
| 段落の要点 | 短い範囲の太字など | 強調なしでも意味が通るか |
| 変数・項目名 | インラインコード | 文章と識別できるか |
| 複数行のコード | コードブロック | コピー時の改行・記号 |
| 条件や注意 | 対象と理由が分かる短い説明 | 色を見なくても注意が分かるか |
| 補足 | 本文の流れに合う注釈 | 小さすぎて読めない表示でないか |
コードは操作条件と結果を組にする
短いstatusやfeatured_mediaのような項目名はインラインコードで示し、複数行はコードブロックへ分けます。次は表示用の架空のJSONです。投稿処理を実行するコードではありません。
{
"title": "表示確認用の下書き",
"status": "draft"
}
コードの前に目的と入力、後に期待する出力や確認先を書きます。コード内部へ注意書きや行番号を混ぜる場合は、コピーしても実行対象へ紛れないかを確認してください。
シンタックスハイライトについて、SWELL公式は別プラグインを案内しています。テーマの標準機能として常に使える前提にせず、導入済みの機能を確かめます。表示のためだけに新しいプラグインを追加する判断は別に行います。
注意点は必要な操作の直前へ置く
取り消しにくい操作の条件は実行前に示すようにします。本文の最後だけに「本番で注意」と書くより、何が変わるか、どの対象を確認するかを具体的に説明します。
見出しは装飾の大きさではなく内容の階層で選びます。注意事項の色やアイコンだけに意味を持たせず、「公開状態が変わる操作」など文字でも対象を示してください。
仕上げにスマートフォンの幅で横スクロール、折り返し、注釈の大きさを見ます。コードをコピーして元の文字列と比べ、引用符や記号が別の文字へ変わっていないかも確認します。
