技術記事の出典は、読者が主張の根拠へ戻れるように付けます。末尾に公式サイトのトップページを並べるだけでは、どの説明を確認したかが分かりません。
主張を支えるページへ直接リンクすることを基本にします。仕様、説明、実行結果を分けると、公式資料で分かることと、手元の検証でしか分からないことも区別できます。
何を確認した資料かを記録する
編集用の記録には主張、資料URL、該当する仕様、確認日、対象バージョンを残します。以下はWordPress APIの日時を説明する場合の例です。
| 記事の説明 | 確認する資料 | 記事での扱い |
|---|---|---|
| dateはサイトのタイムゾーン | Posts APIのdateフィールド | 公式仕様として説明 |
| date_gmtはGMTの日時 | 同ページのdate_gmtフィールド | dateとの違いを示す |
| 自サイトで保存した日時 | 実行記録と保存値 | 実行した場合だけ結果を記載 |
| 公開が遅れた原因 | Cronやサーバーの記録 | 仕様だけで原因を断定しない |
同じ公式資料でも、記事の全結論を裏付けるとは限りません。資料が説明している範囲を読み、推測や運用上の提案は分かる形で書きます。
引用、要約、自分の判断を分ける
引用は原文を変えず、引用範囲と出典が分かる形にします。要約では語順を変えるだけで済ませず、意味、条件、確度を保って自分の説明へまとめます。
運用上の判断なら「この例では」「編集上の確認項目として」など、資料の必須条件と区別します。公式資料にない独自の件数や合格基準を、公式の推奨値として書かないでください。
未実行のコードを動作確認済みと書かないことも出典管理の一部です。構文確認、ローカルの架空データでの実行、実サービスでの実行はそれぞれ記録を分けます。
読者向けのリンクを配置する
重要な仕様の説明にはその近くで資料名や確認先を示します。末尾の一覧は補助として使い、リンク文言は「こちら」より「Posts APIの日時フィールド」のように対象が分かる形にします。
公開前はURLが開くかに加え、リンク先に説明した仕様が残っているかを読みます。200が返るページでも、内容が変わったり別の案内へ移ったりする場合があります。
更新時は出典の変更に合わせて本文、コード、FAQなど関連する説明も見直します。リンク数を増やすことや公式という名前を置くことだけで信頼性が確保できるとは考えず、根拠と主張の対応を保ちます。
