plexy-markdown

plexy-markdown

簡潔な Markdown は素早くスキャンでき、差分も見やすくなります。1行に1つのアイデアを書き、残りはネストします。

フォーマット

• 箇条書き1つにつき、文は1つにします。
  • 文とは、単一の主張、手順、事実、またはルールです。
  • 箇条書きで「and」「then」「which」やダッシュを使って2つのアイデアをつないでいる場合は、分割します。
• 文の一部はサブ箇条書きにします。
  • 構造がわかるようにネストします。親項目で対象を示し、子項目で説明します。
  • 2、3階層あれば十分です。それ以上深くなる場合は、構造に問題があります。
• すべての行を120文字未満にします。
  • 上限は読みやすさのための目安であり、書式ルールではありません。
  • 行を折り返す前に、節の切れ目でサブ箇条書きに分けます。
• 簡潔にします。
  • 意味が変わらない語句を削ります（「とても」「本当に」「〜するために」「注意すべき点として」など）。
  • つなぎの言葉だけの見出しや、内容のない見出しを省きます。

例

悪い例 — 複数のアイデアが混在する長い箇条書き：

デプロイパイプラインはイメージをビルドし、レジストリにプッシュし、マニフェストを更新し、Podを検証します。

良い例 — 親項目と子項目：

- The deploy pipeline has four stages.
    - Build the image.
    - Push it to the registry.
    - Update the manifest to trigger a rollout.
    - Verify the pods are healthy.

悪い例 — ダッシュでつないだ断片：

• このサービスは高速です - 応答をキャッシュし - 障害時には再試行します。

良い例：

• このサービスは高速です。
  • 応答をキャッシュします。
  • 障害時には再試行します。

ルールの例外

• コードブロック、表、フロントマター、URLは対象外です。
  • コード、URL、表のセルは、折り返すと壊れる可能性があります。
  • 内容を損なうくらいなら、行が長くなっても構いません。
• 文字数制限に合わせるために、内容を削除しないでください。
  • サブ箇条書きに再構成します。本当に長い単一の文は、そのままにして構いません。
• ユーザーが変更を求めていない文章を書き換えないでください。
  • 自分が書いたり編集したりする箇所にスタイルを適用し、無関係なファイルには適用しません。
• ドキュメントの既存の構造を維持してください。
  • 箇条書きを使うためだけに、見出し、表、番号付き手順を統合しないでください。

理由

• 1行に1つのアイデアを書くと、読者は冒頭の言葉を拾い読みするだけで全体像を把握できます。
• 短い行は、幅の狭いターミナルでも読みやすく、横並びの差分でも見やすくなります。
• サブ箇条書きは、文章では見えにくい親項目と詳細の関係を示します。
• 簡潔な箇条書きはトークンの消費を抑え、編集のたびに発生するマージコンフリクトも回避しやすくなります。