이 문서는 이로부터 적응되었습니다. Jack Bradshaw의 . 스타일 지침 모노레포 효과적인 문서화는 지속 가능한 개발의 기초입니다; 그러나, 팀 성장의 불가피성은 분열 및 불일치가없는 팀으로 문서를 작성하는 것이 어렵습니다; 따라서 기여자 간의 조정이 필요합니다. 심지어 한 번 무료 패스가 있었던 솔로 엔지니어도 이제 AI 생성 문서의 불일치와 싸워야합니다. 이 문제를 해결하기위한 나의 첫 번째 시도는 13 개의 규정 규칙을 포함하는 일반 문서 표준 문서의 창조로 끝났다; 특히: 문서는 비인간적이고, 객관적이고, 정확하며, 형식적이며, 문자 그대로, 현재, 계약적이며, 비정상적이며, 설명적이며, 최종적이며 선언적이어야합니다. 그것은 예술 작품이었고, 결함이 없고, 숭고한 승리였습니다. 내 의도는 AI에 의해 객관적으로 검증되고 시행 될 수있는 명확한 표준을 설정하는 것이 었습니다. 그러나 문제는 시간이 지남에 따라 명백해졌습니다. 특히 일부 요구 사항이 객관적으로 검증 될 수있는 반면 (리스트 형식과 같은), 다른 것들은 본질적으로 주관적이었습니다 (흥미 부서진 표준을 반복하는 대신에 접근 방식에 근본적인 변화가 필요했습니다. 나는 문서를 완전히 새롭게 작성하고 내용을 세 가지 유형으로 나누었습니다 : 표준 (절대적이고 객관적), 관행 (직관적이지만 명확하게) 및 지침 (매우 주관적이고 불확실한), 지침에 대한 심각한 변화. 고정 규칙 대신 높은 수준의 지침에 초점을 맞추고 반대방향 사이의 중간 지점을 장려함으로써, 새로운 지침은 알려진 항 패턴 및 실패 모드를 억제하면서 개별적인 표현을위한 넓은 공간을 제공합니다. 이것은 기여자가 결과에 과도한 불일치없이 자연스럽게 말할 수있는 포괄적 인 공간을 만듭니다. 제목 : Reasoned Wisdom 리포지토리 문서는 객관적이고 사실 기반이어야 하며, 코드베이스와 적절한 경우 외부 소스에 대한 참조가 있어야 하며; 그러나, 열심히 획득한 경험의 형태의 주관성은 가치가 없으므로, 사실들만이 유용한 맥락이 부족하며, 기여자의 독특한 경험/전망을 피하는 것은 지원적인 환경을 창출하지 않으므로, 문서에는 객관성과 주관성의 균형이 있어야 한다. FooSort는 O(N log N)의 평균 사례 계산 복잡성을 공식적으로 헨더슨 (1984)에 의해 잠재적 기능과 집계 방법을 사용하여 암호화된 분석을 통해 입증했다. 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]. Too Poetic : "FooSort는 우아한 발레처럼 데이터를 통해 춤을 추고, 우아하게 그들의 정당한 장소에 요소를 삽입합니다. 그것은 매번 효율성을 속삭이고, 혼돈에서 질서를 조작하는 비교의 심포니아. Just Right: "FooSort는 O(N log N) 평균 시간에 N 항목을 분류하여 대부분의 사용 사례에 적합합니다.그러나 회사 X에서 고객 업로드가 일반적으로 사전 분류되었을 때 생산 문제를 일으키는 보고 분류 된 데이터에서 O(N2)로 분류됩니다. 객관성과 주관성 사이의 균형을 잡는 것은 문서가 정확하고 접근성이 유지되며 동시에 기여자들에게 포괄적이고 지원적인 공간을 창출합니다. 가이드라인 : 부족함과 미니멀리즘의 균형 기여자는 몇 개의 여분의 구절 (킬로바이트)을 저장하는 비용이 부족한 맥락의 비용보다 훨씬 낮기 때문에 (예를 들어, 디버깅 시간, 생산 실패, 바퀴를 재 발명); 그러나 불필요한 세부 사항은 불필요한 세부 사항으로 진실을 어둡게함으로써 목적을 이길 수 있습니다; 따라서 문서는 불필요한 정보를 제외해야합니다. Too Minimal: "FooProvider 캐시 값." (행동, 만료 또는 알려진 문제에 대한 불충분한 컨텍스트) Too Verbose : "FooProvider는 16의 초기 용량과 0.75의 로드 요소를 가진 ConcurrentHashMap 인스턴트를 내부적으로 사용하여 캐시 값을 저장하여, 이는 System.nanoTime()에서 유래한 64비트 타임스탬프를 포함하는 사용자 지정 CacheEntry 개체에 포장되어 있으며, 일반적으로 OOM 오류로 인해 Android 장치에서 종종 실패합니다."(대체적인 OOM 실패를 묻는 과도한 구현 세부 사항) Just Right: "FooProvider는 LRU 추방 정책을 사용하여 60초 TTL 값을 캐시합니다.The cache runs on a background thread and may cause OOM errors on memory-constrained Android devices."(비필요한 구현 세부 사항없이 행동 및 알려진 문제에 대한 충분한 컨텍스트). 미니멀리즘 (필요하지 않은 세부 사항을 피하는)과 충분성 (적절한 맥락을 제공하는) 사이의 균형을 잡는 것은 문서가 과도한 구현 세부 사항에 따라 중요한 정보를 어둡지 않고도 유용하고 접근 할 수 있도록합니다. 가이드라인 : 과거, 현재 및 미래의 균형 기록은 계획이 변경될 때 미래를 문서화하면 부정확성이 발생할 수 있으며, 과거를 문서화하면 저장소를 오래된 정보로 혼란스럽게 할 수 있기 때문에; 그러나, 역사적 맥락은 종종 현재를 정당화하면서 역사가 반복되는 것을 방지하고, 미래 작업의 기회를 인식하면 알려진 결함을 강조한다; 따라서, 과거와 미래는 유용한 곳에서 참조되어야합니다. 너무 과거 집중: "이 방법의 과거 구현은 표준 수학 라이브러리를 사용했습니다. 분석기와 관련된 문제가 있었지만 수정되었습니다." (행동 가능한 맥락이없는 무관한 세부 사항) Too Future-Focused: "Q4에서는 분석기를 다시 작성할 계획입니다.We will make this method asynchronous in v2.0." (현재 상태에 대한 컨텍스트가없는 약속) Just Right: "표준 라이브러리 파서가 v1.2에서 성능 회귀를 일으키기 때문에 사용자 지정 파서가 사용됩니다.This method is synchronous, but asynchronous support may be added in a future release (tracked by issue #123)." (Present state justified by historical context and known limitations recognized with tracking reference). 안정성 (존재하는 것을 문서화)과 맥락 (필요한 배경을 제공) 사이의 균형을 잡는 것은 문서가 정확하고 유용한 역사를 보존하고 알려진 제한을 인식하면서 유용하게 유지되도록 보장합니다. 참고: 미래 계획을 외부 추적 참조와 연결하면 독자가 추적하고 업데이트를 얻을 수 있는 방법을 제공합니다. 가이드라인: Precision with Simplicity의 균형 문서화는 기술적으로 정확하고 정확해야 하며, 모호한 설명은 오해와 잘못된 사용을 초래할 수 있기 때문에; 그러나 과도한 기술적 세부 사항은 핵심 개념을 어둡고 독자를 압도 할 수 있습니다; 따라서, 기여자는 불필요한 복잡성없이 정확한 설명을 제공해야합니다. Too Vague: "FooProvider는 당신이 그들을 필요로 할 때 개체를 만듭니다." (행동에 대한 기술적 정확성이 부족합니다) Too Detailed: "FooProvider는 공장 패턴 인스턴티션 메커니즘을 사용하여 액세서리 방법의 각 호출은 새로운 운영자를 통해 집합 메모리의 할당을 유발하여 자신의 메모리 주소가있는 독특한 Foo 인스턴스의 구축을 결과로합니다." (대량의 기술적 세부 사항은 간단한 행동을 어둡습니다) Just Right: "The FooProvider creates a new instance of Foo on every call." (필요하지 않은 복잡성없이 정확한 기술적 설명). 정확성 (기술적으로 올바른 것)과 단순성 ( 이해할 수있는 것) 사이의 균형을 잡는 것은 문서가 구현 세부 사항으로 독자를 압도하지 않고 정확한 정보를 전달할 수 있도록합니다. 가이드라인 : 비공식성과 형식성의 균형 문서화는 신뢰성과 명확성을 유지하는 전문 언어를 사용해야하며, 비공식 슬랑이는 독자를 이기고 인식 된 권한을 줄일 수 있기 때문에; 그러나 과도한 학문적 또는 공식적인 표현은인지 장벽을 만들고 독자를 멀리합니다. 너무 비공식 : "Kotlin의 컴파일러는 꽤 멋지며 코드를 bytecode 또는 JVM 및 stuff와 같은 다른 플랫폼을위한 무엇이든으로 변환합니다." 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.)" (명확하고 표준적인 용어로 전문적인 톤). 공식성 (전문성 유지)과 비공식성 ( 접근 가능) 사이의 균형을 잡는 것은 문서가 일반 엔지니어에게 접근 할 수있는 동시에 신뢰할 수 있고 권위있는 것을 보장합니다. 지침: 특정 그룹 참조 문서화는 종종 의사결정과 행동 뒤에있는 사람이나 팀을 참조하도록 요구되며, 배정은 책임감과 맥락을 제공하기 때문에; 그러나 개인 별명 ( "우리", "나", "우리", 등)은 불분명합니다; 따라서 기여자는 가능하면 특정 개인 / 그룹 이름을 사용해야합니다. 너무 불확실하다 : "The FooProvider is recommended." (누가 추천합니까?) Too Vague : "우리는 운전자를 제거하기로 결정했습니다." (누구 "우리"를 의미하는지 불분명) Just Right : "Kernel 팀은 런타임 성능을 위해 드라이버를 제거하기로 결정했습니다." (명확한 이유로 특정 할당). 부여 (책임성과 맥락을 제공)과 명확성 (분명한 대칭을 피하는) 사이의 균형을 잡는 것은 구체적인 그룹 참조(예: "The Maintainers", "The Compiler Team", "The Security Workgroup")를 사용하여 명확한 커뮤니케이션을 보장합니다. 예외: 사용자(예를 들어 "당신")를 참조하는 프론트는 허용됩니다 (balance declarative 및 imperative tone와 관련이 있습니다). 가이드라인 : 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." (단계별 지침이 필요한 튜토리얼에서 수동적인 설명) Just Right: "Reference documentation: FooProvider must be configured before use by calling init().Tutorial: generate the artifacts by running bazel run //foo:bar." (시스템 설명에 대한 선언 톤, 절차 지침에 대한 필수 톤). 선언적 (시스템을 정의하는)과 필수적 (독자를 안내하는) 사이의 균형을 잡는 것은 문서가 그 맥락에 적절한 정보를 제공하는 것을 보장하며, 참조 문서가 유물과 튜토리얼에 초점을 맞추고 명확한 실행 가능한 단계를 제공합니다. 가이드라인: 겸손과 자신감의 균형 문서는 내용이 잘 이해되었을 때 자신감으로 작성되어야하며, 불필요한 보안은 권위에 영향을 미치고 아무것도 존재하지 않는 곳에서 의심을 일으키기 때문에; 그러나 진실이 불확실할 때 과도한 확신으로 말하면 신뢰성에 영향을 미칠 수 있습니다. 너무 망설임 : "FooProvider는 아마 스레드 안전하지 않으며 실행 시간 실패의 작은 위험이 있습니다." (알 수없는 행동에 대한 불필요한 보안) 너무 자신감 : "FooProvider는 확실히 높은 메모리 압력 하에서 작동 합니다." (검증되지 않은 행동에 대한 잘못된 확신) Just Right: "FooProvider는 thread-safe가 아닙니다.The behavior under high memory pressure is undefined and has not been tested."( 알려진 사실에 대한 자신감, 알려지지 않은 것에 대한 정직). 신뢰(권한을 확립하는 것)과 겸손(한계를 인정하는 것) 사이의 균형을 잡는 것은 불필요한 의심을 일으키지 않고도 문서의 신뢰성을 유지할 수 있도록 합니다. 원칙 : 중립성과 균형 판단 기여자는 실제 문제, 제한 사항 및 제한 사항을 식별하기 위해 판단력을 행사해야하지만, 시스템, 플랫폼 또는 기여자를 공격하는 판단 언어는 쓸모가 없습니다. 너무 중립적 : "이 구현은 모든 곳에서 작동합니다." (정의가 부족하고 실제적인 제약을 무시합니다) 너무 판단 : "안드로이드는이 똥을 실행할 수없는 그런 똥 운영 체제입니다, 또한 누가이 똥을 썼습니까?" (플랫폼과 사람들에 대한 개인 공격) Just Right: "Android 기기 약 2012 메모리 제한이 이 구현이 예정대로 작동하는 것을 방지합니다.The Foo 구현은 Android에서 작동하지 않습니다." (사운드 판단 특정, 정보 및 사실 설명). 판단 (실제 문제와 제약을 식별하는)과 중립성 (개인 공격과 비난을 피하는) 사이의 균형을 잡는 것은 문서가 판단주의에 의존하지 않고도 정확하고 유용한 정보를 제공합니다. 가이드라인 : 존중과 균형 잡힌 고려 기여자는 잠재적 인 어려움을 인식하고 지지적 인 지침을 제공함으로써 독자에 대한 고려를 보여야하며, 적절하게 사용되는 부드러운 언어를 사용해야합니다.그러나 독자의 정신적 또는 신체적 능력에 대한 주장과 가정은 비효율적 일 수 있습니다.그러므로 문서는 옵션과 조언을 제공해야하며 독자에게 의심의 이점을 제공하고 개인적인 평가를 피해야합니다. Too Dismissive : "이 행동은 분명하고 이해하기 쉽습니다." (읽기의 잠재적 인 도전에 대한 고려가 부족합니다) Too Presumptuous: "당신은 아마도이 개체를 혼란스럽게 찾을 것이며, 당신이 갇혀있을 때 아마도 문제 해결 가이드를 읽어야합니다." (읽기의 능력과 경험에 대한 주장) Just Right: "이 개체는 인터페이스 계약을 완전히 구현하지 않으며 예기치 않은 방식으로 오류를 발생시킬 수 있습니다.Callers may wish to use Bar instead for a production ready service. Full documentation is provided in the README." (Accepts limitations, offers options, remains neutral and respectful). 고려 (잠재적 인 도전을 인식)과 존중 (독자에 대한 추측을 피하는) 사이의 균형을 잡는 것은 문서가 개인적 경계를 넘거나 능력에 대한 추측을하지 않고도 지지적 인 지침을 제공합니다. 가이드라인: Balance Abstraction with Clarity 문서화는 시스템의 설계와 일치하는 적절한 추상화를 사용해야 하며, 추상화는 불필요한 구현 세부 사항을 숨기고 이해를 돕기 때문에; 그러나, 묘사 및 다채로운 언어는 개념적 간접의 층 아래에서 진리를 어둡게 할 수 있습니다; 따라서, 기여자들은 시스템 행동의 명확하고 직접적인 설명에 초점을 맞추어야합니다. "Foo는 컨베이어 벨트처럼 작동하며, 벨트의 첫 번째 바가 처리되고, 다음 벨트가 비어있을 때까지, 그리고 운영자가 할 일이 없을 때 점심 식사를합니다." (메타포는 의미를 무시합니다) Too Imperative: "Foo는 각 바 개체를 노드로 포장하고, 각각 다음/전 노드에 대한 링크를 가지고 있으며, 노드(마크된 루트 노드)에 대한 참조를 보유하고, 나중에 노드 간의 링크를 반복적으로 추적하여 추가된 순서로 처리합니다. Just Right: "Foo는 FIFO 꼬리를 사용하여 바 개체를 처리하고, 꼬리가 빈 상태에서 빈 상태로 유지합니다.Foo는 pub-sub 패턴을 사용하여 바 개체를 비동기적으로 처리합니다."(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: 모든 패키지에 해당 패키지에 대한 세부 사항만 포함된 README, 패키지의 관계에 대한 개요나 맥락이 없습니다. Just Right : 리포토리 구조와 철학을 소개하는 루트 README, 대형 패키지에 대 한 더 작은 조각 READMEs. (평균 배포 모두 개요 및 세부 사항). 대화(정보가 중요한 곳에 가까워지는 것)과 연관성(일반적인 그림을 제공하는 것) 사이의 균형을 잡는 것은 문서가 압도적이거나 분열되지 않고도 접근할 수 있도록 합니다. 참고: 디렉터리의 문서를 같은 디렉터리의 여러 파일로 분할하면 정보가 올바른 위치에 있지만 문서가 너무 커질 때 도움이 됩니다. 실습: 범위 적절한 문서화 Granular 문서(예: Javadoc, inline comments)는 그들이 관련된 구성 요소에 초점을 맞추어야 하며, 고급 문서(예: READMEs, 아키텍처 문서)는 구성 요소가 어떻게 통합하고 함께 구성하는지, 그리고 그들이 더 넓은 시스템에 어떻게 적합하는지에 초점을 맞추어야 한다. 긍정적 예: Javadoc는 함수의 매개 변수, 반환 값 및 가장자리 사례를 설명합니다. 부정적인 예제: Javadoc는 전체 시스템 아키텍처를 설명합니다. 긍정적 인 예 : 패키지의 상호 작용과 전체 디자인 철학을 설명하는 README. 부정적인 예제: README는 각 기능의 내부 구현을 설명합니다. 이것은 독자가 과도하거나 범위 불일치없이 적절한 수준의 추상화에서 적절한 정보를 찾을 수 있도록합니다.This ensures readers can find appropriate information at the appropriate level of abstraction without redundancy or scope mismatch. 표준 : American English 미국 영어는 도메인 협약이 다르게 규정하는 경우를 제외하고는 사용해야 합니다 (예를 들어, 제3자 패키지에서 Colours 개체를 참조하는 경우). 긍정적 인 예 : “색” 부정적인 예: “색” 이것은 코드베이스 전반에 걸쳐 일관성을 보장하고 일반적인 소프트웨어 엔지니어링 협약과 일치합니다. 예외: 문서화되는 기본 API/시스템이 다른 언어를 사용하는 경우 문서화가 일치해야 합니다. 상품명 : 올바른 글쓰기 모든 글쓰기는 정확해야 한다. 긍정적 인 예 : "필요 사항" 부정적인 예: “요구” 이것은 전문성을 유지하고 잘못된 의사 소통을 방지합니다. Standard: No Comma After Abbreviations에 대한 리뷰 보기 Commas는 단축 후에 제거되어야합니다. 긍정적 인 예 : “etc.” 부정적인 예: “etc.” 이것은 시각적 혼란을 줄입니다. 표준 : No Ampersands 단어 "and"는 ampersand 상징 "&" 대신에 사용해야합니다. 긍정적 인 예 : "Standards and Practices" 부정적인 예제 : "Standards & Practices" 이것은 공식적인 쓰기 협약을 준수하고 접근성을 향상시킵니다.
