技術文書コラボレーション Skill

執筆の基盤

• まず結論を述べ、その後に理由を説明します。階層は3層を超えないようにし、ピラミッド構造に従います。最上層は一文の結論、次の層は2〜5個の要点に分解し、さらに裏付けとなる証拠を補足します。
• 事実の正確さを優先します。推測したり、元の情報を勝手に拡張したりせず、用語は統一し、追跡可能にします。必要に応じて、引用と元のデータを保持します。
• 文は短文と能動態を保ち、数値には単位を付け、テンプレート化された口調を避けます。Markdown の見出しは4レベル以下にし、インラインコードはバッククォートでコマンド/パスをマークします。
• 範囲と読者を限定します。最初の段落で目標、読者のペルソナ、デフォルトの前提知識、および範囲外の内容を説明します。

紹介/説明型ドキュメント

1. 冒頭の段落で What/Why/Outcome を説明し、背景、現状、および読者対象を指摘します。
2. 2〜5個の、結論を先に述べ、その後に証拠を示すサポート要点をリストアップします。要点または短いセクションを使用できます。
3. 展開する際には、プロセス、境界、典型的な反例を網羅します。新しい概念を導入する際には、まず直感的な例と全体像を示し、その後で正式な定義、シナリオ、および適用できない状況を補足します。

早見/SOP ドキュメント

• 冒頭の一文でタスクと期待される結果を説明し、続いて1〜3行のリストで適用範囲、前提条件、リスクまたは権限を説明し、すぐに最短の利用可能な例を示します。
• 「インデックス → 分類 → カード」構造を採用し、各カードは「名称/意図 → 最短の例 → 一般的なパラメータ → よくあるエラー → 関連資料」に従います。
• 空からステップを追加したり、仮定を設けたりしてはいけません。追加する必要がある場合は、「要確認/追加推奨」とマークし、根拠を説明します。
• コードブロックは bash/sh でマークし、プロンプトは含めず、コマンドは直接コピーして実行できるようにします。プレースホルダーの説明を提供し、必要に応じて --dry-run または読み取り専用バージョンを優先します。

情報の境界と引用

• 原文に記載されていない結論やデータを追加しないでください。誤字脱字や数値を修正する前に、原因を確認して記録する必要があります。
• 重要な定義、API、プロトコルは信頼できるソースから引用し、リンク、バージョン、およびアクセス日を明記します。複数のソース間で矛盾がある場合は、差異と採用理由をリストアップします。
• コマンド、コード、図表の意味は変えずに、フォーマットとコメントのみを最適化します。サンプル出力には「例」とマークする必要があります。

レイアウトと Markdown の詳細

• 見出しとリストの階層は2層に制限し、長い段落はリストまたはテーブルに分割します。比較と検討は、テーブルまたは並列セクションを使用して表示します。
• インラインコードは識別子またはコマンドのみを囲み、句読点はバッククォートの外側に記述します。設定例は、ネイティブ構文で表示します。
• コードブロックはステップごとに分割し、実行権限を説明します。長いコマンドは、必要に応じてバックスラッシュで改行し、末尾にスペースを入れないようにします。
• リンクアンカーは可読性があり、安定している必要があります。外部リンクにはバージョンまたはコミット番号とアクセス日を明記します。画像には代替テキストが必要です。

コラボレーションのヒント

• 情報が不足している場合やコンテキストが不明確な場合は、まず関連する開発者/作成者に確認してから、ドキュメントを拡張または公開する必要があります。
• 潜在的な競合やリスクポイントを発見した場合は、まずドキュメントで注意を促し、議論の記録を同期して、その後のメンテナンス担当者が追跡できるようにします。