この文書は、改訂されたものから ジャック・ブラッドショーの . スタイル指令 モノレポ 効率的なドキュメントは持続可能な開発の基盤であるが、チームの成長の不可避性により、分断的で不一致でないチームとしてドキュメントを書くことは困難であるため、貢献者間の一定の連携が必要である。 この問題を解決する私の最初の試みは、13の規定規則を含む一般文書標準文書の作成で頂点となった;具体的には:文書は非人格的で、客観的で、正確で、形式的で、文字通り、現在的で、契約的で、明確で、記述的で、最終的で、宣言的でなければなりませんでした。それは芸術の作品であり、無欠点で、崇高で、そのモノンモノラルな失敗でしか競争しなかった勝利でした。私の意図は、AIによって客観的に検証され、実施されることのできない曖昧な基準を確立することでした。しかし、問題は時間とともに明らかになりました。具体的には、いくつかの要件が客観的に検証されることができた(リストの形式など)、他の人々 壊れた基準を繰り返す代わりに、アプローチの根本的な転換が必要となりました。私は完全に文書を書き直し、内容を3種類に分割しました:基準(絶対的で客観的)、実践(主観的だが曖昧)およびガイドライン(高度に主観的で曖昧な)、ガイドラインに向かって重い転換を必要としました。高レベルのガイドリングに焦点を当て、固いルールではなく、対立する極端の間の真ん中を奨励することによって、新しいガイドラインは、既知の反パターンおよび失敗モードを抑制しながら個人の表現のための広範なスペースを提供します。 タイトル: Reasoned Wisdom リポジトリ文書は客観的で事実に基づき、コードベースおよび適切な場合に外部のソースへの参照を含むものでなければなりませんが、苦労した経験の形での主観性は貴重であり、事実だけが役に立つ文脈を欠いており、貢献者のユニークな経験/視点を避けることは、支援的な環境を作成しないため、文書には客観性と主観性のバランスが含まれるべきです。 Too Academic: "FooSort exhibits O(N log N) average-case computational complexity, as formally proven by Henderson (1984) via amortized analysis utilizing potential functions and aggregate methods. Empirical validation was conducted through Monte Carlo simulation across 10,000 uniformly distributed datasets, yielding a 95% confidence interval of [0.98N log N, 1.02N log N]. The algorithmic soundness has been peer-reviewed and published in ACM Transactions (DOI:10.1145/12345)." (不必要に密集した学術言語) Too Poetic: "FooSort は美しいバレエのようにデータを通して踊り、優雅にその正当な場所に要素を織り込む。 それは毎回効率をささやく、混沌から秩序をオーケストラする比較のシンフォニーです。 雷のように速く、日没のように美しく、それはあなたの混乱したリストを純粋な調和の原始的なアーレイに変換します。 Just Right: 「FooSort は O(N log N) の平均時間で N アイテムを分類し、ほとんどの用例に適しているが、その結果、会社 X で顧客のアップロードが通常事前に分類されたときに生産問題を引き起こした報告されたデータで O(N2) に劣化する」 (客観的な事実と主観的な経験と合理的な結論を組み合わせる)。 客観性と主観性のバランスをとることは、ドキュメントが正確でアクセス可能であることを保証する一方で、貢献者にとって包括的で支援的な空間を作り出します。 原題:Balance Minimalism with Sufficiency 貢献者は、いくつかの余分な段落(キロバイト)を保管する費用が、文脈の欠落(例えば、デバッグの時間、生産の失敗、車輪の再発明)よりもはるかに低いため、ドキュメントの欠落のコストは、ドキュメントは不要な詳細に真実を隠すことにより、不要な詳細が目的を打ち負かす;しかし、ドキュメントは不要な情報を省略すべきである。 Too Minimal: "FooProvider caches values."(行動、期限終了、または既知の問題に関する不十分な文脈) Too Verbose: "FooProvider は内部で ConcurrentHashMap を 16 の初期容量と 0.75 のロード因子でインスタンス化してキャッシュされた値を格納し、CacheEntry オブジェクトに 64 ビットのタイムスタンプが System.nanoTime() から由来するカスタマイズされたCacheEntry オブジェクトに包装されており、OOM エラーの原因で Android デバイスで最も最近使用されたポリシーを使用して削除可能である。 Just Right: "FooProvider cache values with a 60-second TTL using a LRU expulsion policy. The cache runs on a background thread and may cause OOM errors on memory-constrained Android devices."(不必要な実装詳細なしに、行動や既知の問題に関する十分な文脈) ミニマリズム(不要な詳細を避ける)と十分性(適切な文脈を提供する)のバランスをとることは、実装の過剰な詳細に基づいて重要な情報を隠すことなく、文書が有用かつアクセス可能であることを保証します。 原題:Balance Past, Present, and Future 文書化はレポジトリの現在の状態に関連するべきであり、将来を文書化することは計画が変化するにつれて不正確なリスクを伴い、過去を文書化することはレポジトリを時代遅れの情報と混乱させることができるため、歴史的文脈はしばしば現在を正当化し、歴史の繰り返しを防ぎながら、将来の作品の機会を認識することは既知の欠陥を強調するため、過去と未来は役に立つ場合に参照すべきである。 Too Past-Focused: "Past implementations of this method used the standard math library. There were problems with the parser but they were fixed." (アクティブな文脈なしの無関係な詳細) Too Future-Focused: "In Q4 we plan to rewrite the parser. We will make this method asynchronous in v2.0." (現在の状態についての文脈のない約束) Just Right: "A custom parser is used because the standard library parser caused performance regressions in v1.2. This method is synchronous, but asynchronous support may be added in a future release (tracked by issue #123)." (現在の状態は歴史的文脈と認識された限界により正当化され、追跡参照によって認められる)。 安定性(存在するものを文書化する)と文脈(必要な背景を提供する)のバランスをとることは、文書が正確で有用な歴史を保存し、既知の制約を認識する一方で役に立つことを保証します。 注: 将来のプランを外部の追跡参照にリンクすると、読者はフォローし、アップデートを取得する方法を提供します。 ガイドライン:Equilibrium Precision with Simplicity 文書は技術的に正確で正確で、曖昧な記述が誤解や誤った使用につながるため、しかし、過剰な技術的詳細はコアコンセプトを覆い、読者を圧倒する可能性があります。 Too Vague: "FooProvider makes objects when you need them."(行動に関する技術的精度が欠けている) Too Detailed: "The FooProvider utilizes a factory pattern instantiation mechanism in which each invocation of the accessor method triggers the allocation of heap memory via the new operator, resulting in construction of a distinct Foo instance with its own memory address." (過剰な技術的詳細は単純な行動を遮る) Just Right: "The FooProvider creates a new instance of Foo on every call." (不必要な複雑さなしの正確な技術的説明) 精度(技術的に正確であること)とシンプルさ(理解可能であること)のバランスをとることにより、ドキュメントは、実装の細かさで読者を圧倒することなく正確な情報を伝達します。 カテゴリ: Balance Formality with Informality ドキュメンタリーは信頼性と明確さを維持する専門言語を使用すべきであり、非公式スランゲンは読者を遠ざけることができ、認識された権威を減らす可能性がありますが、過度の学術的または形式的な表現は認知的障壁を作り、読者を遠ざけるので、貢献者は明確で標準的な技術的な英語を使用するべきです。 Too Informal: "Kotlinのコンパイラはかなりクールで、あなたのコードをバイトコードまたはJVMやその他のプラットフォームのために何でも変換します。 Too Formal: "Kotlin's compilation process culminates in generation of bytecode for the Java Virtual Machine and analogue artifacts for alternative execution substrates." (過度に学術的な表現が意味を曖昧にする) Just Right: "Kotlin compiles to the JVM and other platforms (e.g. JS, native.)" (明確で標準的な用語を含むプロのトーン) 形式性(プロフェッショナリズムを維持する)と非公式性(アクセス可能である)のバランスをとることは、ドキュメントが信頼性と権威性を保ちながら、一般的なエンジニアにアクセスできることを保証します。 タグ: 特定グループ参照 文書化はしばしば決定や行動の背後にある人々やチームを参照することを必要とし、割り当ては責任と文脈を提供するため、しかし、個人名称(「我々」、「私」、「我々」など)は曖昧であるため、貢献者は可能な限り特定の個人名/グループ名を使用すべきである。 Too Vague: "The FooProvider is recommended." (誰が推薦するのか?) Too Vague: “We decided to remove the drivers.” (誰を指すのか不明) Just Right: "The Kernel Team decided to remove the drivers for runtime performance." (明確な理由を持つ特定の属性) 割り当て(責任と文脈を提供する)と明確さ(曖昧な名詞を避ける)のバランスをとることは、曖昧な名詞ではなく、特定のグループ参照(例えば「The Maintainers」、「The Compiler Team」、「The Security Workgroup」)を使用して明確なコミュニケーションを確保します。 例外:ユーザ(例えば「あなた」)を指す口頭は、許容可能である(バランス宣言音と強制音に関連する)。 タイトル: Balance Declarative and Imperative Tone 文書は、その行為と特性を述べることによって、リポジトリのコンテンツを記述するべきであるため、これは、その中に含まれているアーティファクトに焦点を当てている;しかし、手順、チュートリアル、ガイドは、直接読者に強制的な指示で書かれた場合、より明確であることができ、それゆえ、貢献者は、文脈にトーンを合わせるべきである。 Too Imperative: "You must configure the FooProvider before you use it. You should call the init() method first." (参照文書のコマンド) Too Declarative: "The //foo:bar target generates artifacts when executed." (Passive description in a tutorial where step-by-step guidance is needed) Just Right: "Reference documentation: FooProvider must be configured before use by calling init(). Tutorial: Generate the artifacts by running bazel run //foo:bar." (システム説明の宣言トーン、手順ガイダンスの imperative tone) Declarative(システムを定義する)とImperative(読者を導く)のバランスをとることは、文書がその文脈に適した情報を提供することを保証し、参考文書はアーティファクトとチュートリアルに焦点を当て、明確な行動可能なステップを提供します。 ガイドライン: 自信と謙虚さのバランス 文書は、内容がよく理解されているときに自信を持って書かれるべきであり、不要なセーリングは権威を損なうこと、存在しないべき場所で疑問を生み出すことから、しかし、真実が不確実であるときには過剰な確信をもって話すことは信頼性を損なう可能性があるため、貢献者は知識の限界を認識し、その不確実性について透明であることによって、自信と謙虚さをバランスをとるべきである。 Too Hesitant: "FooProvider is probably not thread-safe and there is a small risk of runtime failure."(既知の行動についての不要なヘッジング) Too Confident: "FooProvider will definitely work under high memory pressure." (テストされていない行動についての間違った確信) Just Right: "FooProvider is not thread-safe. The behavior under high memory pressure is undefined and has not been tested."(既知事実について自信、未知について正直) 信頼(権威を確立する)と謙虚さ(限界を認識する)のバランスをとることは、文書が不必要な疑問を生み出すことなく信頼性を維持することを保証します。 原題:Balance Judgment with Neutrality 貢献者は、実際の問題、制限、制限を特定するために判断力を行使すべきであるが、システム、プラットフォーム、または貢献者を攻撃する判断言語は役に立たない。 Too Neutral: “This implementation works everywhere.”(判断が欠け、実際の制約を無視) Too Judgmental: "Android is such a shit operating system it can't even run this, also who wrote this shit?" (プラットフォームと人に対する個人的な攻撃) Just Right: "Android devices around 2012 have memory limitations that prevent this implementation from working as intended. The Foo implementation does not work on Android." (Sound judgment with specific, informative, and factual descriptions) (Androidのデバイスには、この実装が予定通りに動作するのを防ぐメモリの制限があります。 判断(実際の問題や制約を特定する)と中立性(個人的な攻撃や責めを避ける)のバランスをとることで、文書は判断主義に頼ることなく正確かつ有用な情報を提供します。 原題:Balance Consideration with Respect 貢献者は、潜在的な困難を認識し、適切に使用される柔軟な言語で支援的なガイドラインを提供することによって、読者に対する考慮を示すべきであるが、読者の精神的または肉体的能力に関する主張や仮定は、重要な人間間の境界を越えると反生産的である可能性があるため、文書は選択肢とアドバイスを提供し、同時に読者に疑いの利点を与え、個人的評価を避けるべきである。 Too Dismissive: "This behavior is obvious and should be easy to understand."(読者の潜在的な課題に対する考慮が欠けている) Too Presumptuous: "You will probably find this object confusing, and you should probably read the troubleshooting guide when you get stuck." (読者の能力と経験について主張する) Just Right: "This object does not fully implement the interface contract, and may throw errors in unexpected ways. Callers may wish to use Bar instead for a production ready service. Full documentation is provided in the README."(制限を認識し、オプションを提供し、中立的で敬意を払う) 考慮(潜在的な課題を認識すること)と尊重(読者についての仮定を避けること)のバランスをとることで、文書は人との境界を越えたり、能力についての仮定をすることなくサポート的なガイドラインを提供します。 ガイドライン: Balance Abstraction with Clarity 文書化は、システムの設計に合致する適切な抽象を用いるべきであり、抽象化は、不要な実装の詳細を隠し、理解を助けるためであるが、物語的でカラフルな言語は、概念的な間接の層の下で真実を隠すことができるので、貢献者は、システムの行動の明確で直接的な記述に焦点を当てるべきである。 Too Narrative: "Foo works like a conveyor belt, the first Bar on the belt is processed, then the next, and so on, until the belt is empty, and the operator goes to lunch when there is nothing to do." (メタフォーは意味を隠す) Too Imperative: "Foo wraps each Bar object as a Node, each with a link to the next/previous node, and holds a reference to a node (marked root node), then recursively follows the links between nodes to process them in the order they were added. All this happens on a background thread for performance." (過剰な実装詳細) Just Right: "Foo processes Bar objects using a FIFO queue, and idles while the queue is empty. Foo uses the pub-sub pattern to process Bar objects asynchronously." (Clear, direct descriptions with appropriate abstraction).Foo processes Bar objects using a FIFO queue, and idles while the queue is empty. Foo uses the pub-sub pattern to process Bar objects asynchronously. (Clear, direct descriptions with appropriate abstraction). 抽象性(実装の詳細を隠す)と明確性(物語の重さを避ける)のバランスをとることは、文書が不必要な概念的間接化なしに実装を明確に説明することを保証します。 ガイドライン:Balance Documentation Proximity with Size ドキュメンタリーは、それに関連するアーティファクトの近くに配布されるべきであるため、これは読者がモノリチックなドキュメントに圧倒されるのを防ぎ、情報を見つけるのに役立ちます;しかし、あまりにも多くのドキュメントに情報を広げることは、意味を暗くし、読者に一貫したイメージを残さないため、貢献者はコロチュレーションと一貫性をバランスをとらなければなりません。 Too Centralized: The root repository README containing documentation for the entire repo. (Overwhelming, difficult to navigate. ) Too Fragmented: A README in each package with details of that package only, with no overview or context about how packages relate. パッケージがどのように関係するかについての概要や文脈がない。 Just Right: A root README that introduces the repository structure and philosophy, with smaller granular READMEs for large packages. (Balanced distribution with both overview and detail) リポジトリの構造と哲学を導入します。 コロラクション(重要な場所に近い情報を保持する)と一貫性(統一されたイメージを提供する)のバランスをとることは、ドキュメントが圧倒的または断片化されずにアクセス可能であることを保証します。 注: ディレクトリ内の文書を同じディレクトリ内の複数のファイルに分割すると、情報が適切な場所にありますが、文書が大きくなっている場合に役立ちます。 実践:適切な文書化 Granular documentation (e.g. Javadoc, inline comments) should focus on the component they relate to; whereas, high-level documentation (e.g. READMEs, architecture docs) should focus on how components integrate and compose together, and how they fit into the broader system. 文書の範囲はその文書の文脈に合致すべきである。 ポジティブな例: Javadoc は、関数のパラメータ、リターン値、およびエッジケースを説明します。 ネガティブな例: Javadoc がシステム構造全体を説明します。 ポジティブな例:パッケージがどのように相互作用するかと全体的な設計哲学を説明するREADME。 ネガティブ 例:README は、各機能の内部実装を説明します。 これにより、読者が適切な情報を抽象化の適切なレベルで見つけることができることを保証します。 スタンダード: American English ドメイン規約が異なる場合を除き、アメリカ英語を使用する必要があります(例えば、第三者のパッケージから Colours オブジェクトを参照する場合)。 良い例:「色」 ネガティブな例:「色」 これにより、コードベース全体で一貫性が確保され、一般的なソフトウェアエンジニアリング条約に準拠します。 例外: 文書化されているベースの API/システムが別の言語を使用している場合、文書が一致する必要があります。 タグ: 正しい字幕 すべての文字が正しくなければなりません。 正しい例:「要件」 ネガティブな例:「要求」 これはプロフェッショナリズムを維持し、誤ったコミュニケーションを防ぐ。 スタンダード:No Comma After Abbreviations コマスは、短縮後に省略する必要があります。 良い例は「etc」です。 ネガティブな例:「etc.」 視覚混乱を減らす。 スタンダード:No Ampersands 「&」の代わりに「and」という単語を使用する必要があります。 ポジティブな例:「基準と実践」 ネガティブな例: "Standards & Practices" これは、正式な書面条約に従い、アクセシビリティを向上させます。
