MENU

SWELL記事でコードと注意点を読みやすく見せる装飾ルール

当ページのリンクには広告(PR)が含まれていることがあります。
SWELL記事でコードと注意点を読みやすく見せる装飾ルールのアイキャッチ

技術記事の装飾は、読者が説明と実行対象を区別するために使います。すべての段落へマーカーを付けると、重要な条件や操作が目立ちにくくなります。

ルールは同じ意味の要素に同じ装飾を使うことです。変数やファイル名、実行するコード、注意事項を分け、見た目を変えるために本文の構造を崩さないようにします。

目次

文章、語句、コードの使い分け

SWELL公式はインラインコードに加え、FILEやDIRの表示、注釈などを案内しています。どの機能を使うかは実際の編集画面とバージョンで確認し、装飾の種類を増やす前に使う意味を決めます。

スクロールできます
対象表示の選び方確認すること
段落の要点短い範囲の太字など強調なしでも意味が通るか
変数・項目名インラインコード文章と識別できるか
複数行のコードコードブロックコピー時の改行・記号
条件や注意対象と理由が分かる短い説明色を見なくても注意が分かるか
補足本文の流れに合う注釈小さすぎて読めない表示でないか

コードは操作条件と結果を組にする

短いstatusやfeatured_mediaのような項目名はインラインコードで示し、複数行はコードブロックへ分けます。次は表示用の架空のJSONです。投稿処理を実行するコードではありません。

{
  "title": "表示確認用の下書き",
  "status": "draft"
}

コードの前に目的と入力、後に期待する出力や確認先を書きます。コード内部へ注意書きや行番号を混ぜる場合は、コピーしても実行対象へ紛れないかを確認してください。

シンタックスハイライトについて、SWELL公式は別プラグインを案内しています。テーマの標準機能として常に使える前提にせず、導入済みの機能を確かめます。表示のためだけに新しいプラグインを追加する判断は別に行います。

注意点は必要な操作の直前へ置く

取り消しにくい操作の条件は実行前に示すようにします。本文の最後だけに「本番で注意」と書くより、何が変わるか、どの対象を確認するかを具体的に説明します。

見出しは装飾の大きさではなく内容の階層で選びます。注意事項の色やアイコンだけに意味を持たせず、「公開状態が変わる操作」など文字でも対象を示してください。

仕上げにスマートフォンの幅で横スクロール、折り返し、注釈の大きさを見ます。コードをコピーして元の文字列と比べ、引用符や記号が別の文字へ変わっていないかも確認します。

関連する記事

公式資料

この記事を書いた人

Watanabeのアバター Watanabe サイト運営者

2020年よりブログ開始。
SEOが思いのほか性にあっていたようで現在に至る。
モットーは「勝率の高い選択をする」
AIは活用するが吉、最後は人間が息を吹き込む。
アートと科学を追求し、日々精進。
―――
収益:6~7桁をウゴウゴ。
サイト:ペラサイト~中規模サイトまで運営中。
案件:1000円以上の案件をメインに取組中。
打ち手:ブラックSEO~ホワイトSEOまで
―――

目次