readable-docs

読みやすいドキュメント

目的は一つ

プロジェクトの技術記録を、ひと目で把握し、活用しやすくします。事実を最優先し、見つけやすさを次に、簡潔さをその次に、自然な表現を最後に重視します。意味を保ちながら、できるだけ少ない言葉で表現します。基本は句やフレーズ、必要に応じて完全な文、関係性を明確にする場合に限り段落を使います。論文やスローガン集ではなく、役立つスライドのメモのように書きます。

このスタイルは、文章の推敲を依頼されたときだけでなく、原文を書くときにも適用してください。現在のタスクやメモリのスキルと併用しますが、追加のレポート、承認手順、ドキュメントを作成するものではありません。

1. 意味を読み取る

• 関連する原文とその文脈を読みます。読者が何を知り、判断し、実行する必要があるかを見極めます。
• 編集では、依頼された範囲内にとどめます。アーカイブ、引用された証拠、無関係なドキュメントを一括で書き換えないでください。
• 事実とその関係性を保ちます。登場人物、行動、原因、条件、例外、否定、選択肢、不確実性を維持してください。観察を規則に、提案を決定事項に変えてはいけません。
• 正確な技術名、パス、コマンド、設定キー、バージョン、日付、数値、単位、参照元を維持します。文章を人間らしく見せるために、具体的な情報、経験、意見、証拠を作り上げてはいけません。
• 必須セクション、出力先のパス、ステータス項目、指示の強さを維持します。「必須」を「してもよい」に短縮するのは、コピー編集ではなく動作の変更です。

2. ひと目で把握できる構成にする

役立つ結論、ステータス、次のアクションを最初に示します。読者が見つけられる内容を示す見出しを使い、「総合分析」のような曖昧な見出しは避け、「失敗後の復旧方法」のように実際の内容を示します。

内容	基本の形式
個別の事実、制約、所見	箇条書き。項目ごとに一つの要点を記載します。例：对象：结论／条件
手順、優先順位、時系列	番号付きリスト。短いアクションを順に記載します
共通の観点に基づく選択肢や変更	比較表。行ごとに一つの観点を示し、セルには違いを簡潔に記載します
パラメーター、状態、証拠	検索に役立つ列がある場合は、簡潔な参照表
因果関係、仕組み、導出	句やリストでは関係性が分かりにくくなる場合に限り、短い段落
コマンド、設定、エラーの原文	コードブロック。説明はブロックの外に記載します

リストや表が不要なら、簡潔な句や文を使います。

表は参照や比較に使い、段落を収める枠として使わないでください。長い根拠説明は表の下、または関連する小見出しの中に移します。主張に不可欠な条件は、その主張のそばに置きます。

リスト項目に複数の独立した要点が含まれている場合は、分割します。階層を深くネストする必要がある場合は、具体的な見出しの下に再構成します。補足条件は、それが説明する要点と一緒に記載します。

内容のない見出し、繰り返される導入や結論、同じ情報を繰り返す複数の形式は避けます。短い概要から、必要な詳細を参照できるようにし、重複を避けます。

3. 冗長な文ではなく、簡潔なフレーズを書く

ユーザーの言語を使います。既定では中国語です。同義語を次々と使い分けず、定着した技術用語は一貫して使います。

• フレーズや短い節を優先します。見出しや文脈から明らかな主語や目的語は省き、複数の主体が考えられる場合は明記します。箇条書きや表の各セルで、完全な文や文末の句読点を必須にしません。
• 差別化要因を先に述べます。「仅首次安装询问」のように書き、「需要说明的是，在首次安装的情况下，系统会进行询问」のような書き方は避けます。
• 行動と効果を直接述べます。「保留本机值」のように書き、「通过相应机制实现对本机值的有效保留」のような書き方は避けます。
• 中身のない前置き、称賛、根拠のない重要性の主張を削ります。「下面将详细介绍」「值得注意的是」「显著提升」「奠定坚实基础」は、実際の意味を伝える言葉ではなく、編集上の合図です。ただし、実際の意味を担う表現は残します。
• 曖昧な主張は、ソースですでに裏付けられている事実に置き換えます。根拠がない場合は、その旨を述べるか、主張を省きます。数字や推薦の声を作り出してはいけません。
• 補足的な理由には、必要に応じて文中に隣接する PS: の注記を使います。必須の注意事項、例外、障害時の対応は補足ではなく本文に記載します。
• 強調は控えめに使います。すべての箇条書きのラベルを太字にしたり、あらゆるところに装飾的なアイコンを追加したり、無理に3点にまとめたり、文の長さを機械的に交互に変えたり、語数のノルマを設けたりしません。
• 作り物の個性、一人称の感情、意図的な誤り、口語的な埋め草を追加しません。受動態、句読点、箇条書き、一般的な中国語の並列表現を機械的に禁止しません。

文体を調整するときや、短くすると意味が損なわれないか判断に迷うときは、references/examples.md を参照します。例はパターンであり、必須の文書テンプレートではありません。

4. 意味と表現を確認する

テキストを返す、または保存する前に、次の点を確認します。

• ソースと照合します。事実、条件、範囲、不確実性、規範的な強さは同じですか。新たな主張を加えたり、注意書きを抜かしたり、主体を入れ替えたりしていませんか。
• 見出し、箇条書きの冒頭、表の見出しだけを確認します。読者は結論、違い、行動を見つけられますか。
• 最も長い箇条書きと表のセルを読みます。意味を保つ最短の表現で、要点は1つに絞られていますか。独立した要点は分割します。箇条書き記号を追加したり、文章を1行に詰め込んだりしても、段落が簡潔になるわけではありません。
• 生の引用、コード、設定、機械可読な構造はそのまま保持します。StrictDoc では、文体を整えるためだけに UID、文法、関係、ステータス、区切り記号を変更せず、文章フィールドを編集します。
• 文書で既に使われている形式チェックを実行します。.sdoc または StrictDoc 設定を変更した後は、ドキュメントのルートから strictdoc export . を実行し、該当するエクスポート内容を確認します。エクスポートの成功は構文が正しいことを示すものであり、文章の品質を保証するものではありません。

求められたテキストまたはファイルの変更を提出します。文章の評価表や、求められていない編集内容の説明は追加しません。ソースの不足により信頼できる書き換えができない場合は、その不足点を簡潔に伝えます。