कोड के रूप में प्रलेखन

1) वास्तुशिल्प सिद्धांत

1. सच्चाई का एक एकल स्रोत। कोड के बगल में वीसीएस में दस्तावेज, आरेख, आरेख, एपीआई विनिर्देश, शब्दावली -।

2. स्वचालित गुणवत्ता जांच। लिंटर्स, स्पेलिंग, लिंक चेकिंग, डॉक्टेस्ट कोड उदाहरण।

3. कलाकृतियों के रूप में विधानसभा। डॉकिंग साइट, पीडीएफ/ईबुक, "बिल्ट-इन संकेत" - रिलीज़ पाइपलाइन का हिस्सा।

4. वर्शनिंग और ट्रेसबिलिटी। डॉक्टर उसी पीआर पर शासन करता है जो सिस्टम के व्यवहार को बदलता है; एडीआर प्रतिबद्ध हैं।

5. भूमिका से उपलब्धता। सार्वजनिक/आंतरिक, रनबुक 'और ऑन-कॉल, एपीआई इंटीग्रेटर के लिए चश्मा।

6. हस्तनिर्मित न्यूनतम। सामग्री, आरेख, निर्भरता रेखांकन, कोड के टुकड़े - स्रोतों से।

2) दस्तावेज़ प्रकार और रेपो संरचना

docs/
index. md architecture/
overview. md contexts/( C4, contexts, boundaries)
components/
data/
schemas/ (JSON Schema, Avro, Proto)
lineage/ (dataflow. md, dq-policies. md)
security/
threat-models/
key-management. md api/
openapi/ (OpenAPI. yaml)
asyncapi/ (.yaml)
grpc/ (.proto)
processes/
rfc/ (RFC-YYYY-XX-Title. md)
adr/ (ADR-0001-title. md)
runbooks/ (incident-.md)
playbooks/
sops/ (standard operating procedures)
product/
user-guides/
how-to/
faq/
i18n/
en/, en/, tr/# assets localization/
diagrams/ (Mermaid, PlantUML, Graphviz)
images/
_templates/ (RFC/ADR/Runbook templates)

• RFC - कार्यान्वयन से पहले समाधान पर चर्चा करें।
• एडीआर - निश्चित वास्तुशिल्प समाधान (संदर्भ समाधान वैकल्पिक के परिणाम)।
• रनबुक/प्लेबुक - घटनाओं और संचालन के लिए चरण-दर-चरण निर्देश।
• कैसे-टू/एफएक्यू - कार्य चरण - परिणाम की जांच करें।
• API चश्मा - OpenAPI/AsyncAPI/Proto SDK पीढ़ी और डॉक के स्रोत के रूप में।
• कोड के रूप में आरेख - Mermaid/PlantUML/Graphviz/C4।

3) शैली और मानक

एकल शैली गाइड (टोन, शब्दावली, शीर्षक टेम्पलेट, उदाहरण)।

विहित शब्दों (EN/RU), उपनाम, निषिद्ध योगों के साथ शब्दावली।

नंबरिंग और संदर्भ: स्थायी एंकर, एडीआर/आरएफसी/कोड के बीच क्रॉस संदर्भ।

yaml title: "Payment Service: Overview"
owner: "payments-team"
reviewers: ["platform", "security"]
last_review: 2025-10-15 tags: ["architecture","payments","pci"]

4) विधानसभा और प्रकाशन

• MkDocs (सामग्री) - सरल, सुविधाजनक, अच्छा नेविगेशन और खोज।
• Docusaurus - प्रलेखन संस्करण और डॉक्स + ब्लॉग; MDX घटक।
• बड़े प्लेटफार्मों के लिए एंटोरा मॉड्यूलर दस्तावेज।

yaml site_name: Platform Docs theme:
name: material features: [navigation. tabs, content. code. annotate, search. suggest]
plugins:
- search
- mermaid2
- mkdocs-awesome-pages-plugin
- macros nav:
- Review: index. md
- Architecture:
- Overview: architecture/overview. md
- Data: architecture/data/index. md
- API:
- REST: api/openapi/index. md
- Events: api/asyncapi/index. md

5) कोड के रूप में आरेख और आरेख

mermaid sequenceDiagram participant C as Client participant G as API Gateway participant S as Service
C->>G: POST /orders
G->>S: createOrder()
S-->>G: 201 + order_id
G-->>C: 201 Created

@startuml
!include <C4/C4_Container>
Person(user, "User")
System_Boundary(system, "Platform"){
Container(api, "API", "HTTP")
Container(db, "DB", "Postgres")
}
Rel(user, api, "Uses")
Rel(api, db, "CRUD")
@enduml

OpenAPI/AsyncAPI को साइट पर प्रदान किया जाता है; एसडीके/क्लाइंट/उदाहरण उनसे उत्पन्न होते हैं।

6) गुणवत्ता: लिंटर्स और प्रलेखन परीक्षण

• markdownlint - Markdown स्वरूपण नियम।
• घाटी शैली/शब्दावली/स्वर।
• वर्तनी - वर्तनी (RU/EN शब्दकोश)।
• लिंकचेक - बाहरी/आंतरिक लिंक, एंकर।
• डॉक्टेस्ट/उदाहरण - कोड स्निपेट निष्पादित करना, सीएलआई/एपीआई संस्करणों को तुल्यकालित करना।
• स्कीमेटेस्ट - OpenAPI/AsyncAPI/JSON स्कीमा/प्रोटो सत्यापन।

yaml name: docs-ci on: [pull_request, push]
jobs:
lint:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: npm i -g markdownlint-cli
- run: markdownlint "docs//.md"
- run: pipx run codespell docs          true
- run: pipx run linkchecker docs/site          true build:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
- run: pip install mkdocs-material mkdocs-mermaid2-plugin
- run: mkdocs build --strict preview:
if: github. event_name == 'pull_request'
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: mkdocs build
- uses: actions/upload-pages-artifact@v3

python docs/snippets/calc. py def add(a,b):
"""Returns sum of a and b.

>>> add(2,3)
5
"""
return a+b

सीआई 'अजगर -m doctest docs/snippets/calc चलाता है। py '।

7) प्रक्रियाएं: अप्रचलन के लिए आरएफसी/एडीआर/समीक्षा और एसएलए

RFC प्रवाह: सर्जक → ड्राफ्ट कॉपी → चर्चा → निर्णय → योजना → कार्यान्वयन → रेट्रो पोस्ट फैक्टो।

ADR प्रवाह: RFC/प्रयोगों के लिए पसंद + संदर्भ को संक्षेप में ठीक करें।

समीक्षा प्रक्रियाएं: स्रोत - 'CODEOWNERS' + 'डॉक-मालिक। yaml '।

अप्रचलन के लिए एसएलए: महत्वपूर्ण लेखों में एन दिनों में समीक्षा के लिए 'अंतिम _ समीक्षा' और अलर्ट है।

markdown
ADR-0007: Select Event Log - Avro + Schema Registry
Date: 2025-10-31
Status: accepted
Context: the evolution of schemes without breaking consumers is required.
Solution: Avro + Schema Registry, backward compatibility.
Implications: tooling, compatibility tests, N services migration.
Alternatives: JSON Schema, Protobuf (rejected due to X/Y).

8) स्थानीयकरण (i18n) और बहुभाषावाद

स्थानीयकरण रणनीति: स्रोत भाषा (EN या RU) → 'i18n/< locale>' शाखाओं द्वारा अनुवाद।

कुंजी और संदर्भ: हेडर/टुकड़ों के लिए "स्थिर-आईडी" स्टोर करें।

जाँच: चरण 'गुम-कुंजी', desyncronization के लिए अलर्ट.

लोकेल शैली: स्थानीय शब्दावली, अमान्य ट्रेसिंग पेपर, स्थानीय यूआई भाषा में कोड के उदाहरण।

9) उत्पाद एकीकरण

बिल्ट-इन हेल्प (इन-ऐप डॉक्स): एमडीएक्स घटक, संदर्भ संकेत।

रिलीज द्वारा संस्करण: टैग/शाखाओं डॉक्स/वीएक्स। Y ', चयनकर्ता संस्करणों वाली एक साइट।

अनुभागों का ऑटो-जनरेशन: OpenAPI/AsyncAPI, GraphQL SDL, CLI '--help' से।

कोड के रूप में चेंजेलॉग: पीआर लेबल द्वारा स्वचालित पीढ़ी (करतब/फिक्स/डॉक्स/ब्रेकिंग)।

10) मेट्रिक्स और प्रलेखन की अवलोकन

डॉक्स एसएलओ: पीआर के बाद समय का निर्माण/प्रकाशन, साइट अपटाइम, दस्तावेज़ उपस्थिति का समय।

आर्टिफैक्ट कवरेज: एडीआर के साथ सेवाओं का हिस्सा, उदाहरणों के साथ एंडपॉइंट का हिस्सा, "हेल्थ चेक" के साथ रनबुक का हिस्सा।

उपयोगकर्ता मेट्रिक्स: अनुत्तरित खोज, गहराई देखना, अंतर्निहित संकेतों का सीटीआर।

गुणवत्ता: लिंटर त्रुटियां/1000 लाइनें, "टूटे हुए लिंक", पुराने लेखों का अनुपात।

11) सुरक्षा और गोपनीयता

रेपो में रहस्य और पीडी निषिद्ध हैं; रहस्य और मास्किंग के लिए लिंक।

एसएसओ के माध्यम से आंतरिक साइट तक पहुंच; सार्वजनिक खंड अलग हो गए।

निर्यात नियम: आंतरिक लिंक के बिना पीडीएफ/अभिलेखागार, गोपनीय दस्तावेजों के लिए वॉटरमार्क।

स्क्रीनशॉट स्वच्छता: स्वचालित गुमनामी (मोक डेटा/धब्बा)।

12) पैटर्न

पीआर में डॉक्स। व्यवहार को प्रभावित करने वाले किसी भी बदलाव में एक ही पीआर में डॉक को अपडेट करना शामिल है।

अनुबंध के रूप में साँचा। एक सेवा/समापन बिंदु/डेटासेट का निर्माण - एक जनरेटर के माध्यम से जो डॉक रिक्त रखता है।

कोड के रूप में चार्ट। CI में कोई चित्र - संपादन योग्य स्रोत, SVG/PNG असेंबली।

डॉक्स पूर्वावलोकन। पीआर के लिए साइट पूर्वावलोकन के लिंक के साथ बॉट टिप्पणी।

कोड में लिंक डॉकिंग। स्रोतों में एनोटेशन ('@ doc: adr/0007') जो साइट पर प्रदान किए जाते हैं।

13) एंटी-पैटर्न

सिंक के कोड के बगल में संस्करण के बिना विकी/नोटिशन में प्रलेखन।

स्रोतों के बिना स्क्रीनशॉट - स्वचालित रूप से अद्यतन करने में असमर्थता।

मौखिक चैट और निजी फाइलों में "गुप्त" ज्ञान।

उदाहरण और अपरिवर्तनों के बिना जेनरिक - बेकार पृष्ठ।

मालिकों की कमी और 'अंतिम _ समीक्षा' - अप्रचलन का एक हिमस्खलन।

मैनुअल असेंबली और प्रकाशन - डॉक की एक नाजुक और दुर्लभ रिलीज।

14) स्वचालन उदाहरण

bash build. sh scripts/render-openapi. sh api/openapi/.yaml > docs/api/openapi/index. md scripts/render-asyncapi. sh api/asyncapi/.yaml > docs/api/asyncapi/index. md

bash linkcheck --config. linkcheck. yml site/

yaml
- name: Deploy Preview run: mkdocs build && npx serve -s site -l 5000 &
- name: Comment with URL uses: peter-evans/create-or-update-comment@v4 with:
issue-number: ${{ github. event. pull_request. number }}
body: "Preview: http ://preview- $ {{github. run_id }}.local"

15) आर्किटेक्ट चेकलिस्ट

1. क्या कोड और स्पष्ट संरचना के बगल में डॉक का एक भी भंडार है?
2. टेम्पलेट (RFC/ADR/Runbook/How-To) और शब्दावली वर्णित?
3. लिंटर्स में शामिल हैं (मार्कडाउन्लिंट, वेले), स्पेलचेक, लिंकचेक और डॉक्टेस्ट?
4. आरेख और चित्र - जैसे कोड, सीआई में विधानसभा?
5. क्या API चश्मा (OpenAPI/AsyncAPI/Proto) साइट पर मान्य और प्रदान किया गया है?
6. विलय द्वारा पीआर और ऑटो-प्रकाशन के लिए संगठित डॉक्स-पूर्वावलोकन?
7. क्या उम्र बढ़ ने वाले SLA (last_review) और पृष्ठों के "मालिक" हैं?
8. मेट्रिक्स: कवरेज, लिंटर त्रुटियां, टूटे हुए लिंक, खोज "शून्य" प्रश्न?
9. सुरक्षा नीतियां: रहस्य प्रतिबंधित, एसएसओ, वॉटरमार्क/निर्यात?
10. स्थानीयकरण शाखाओं द्वारा नियंत्रित किया जाता है और चूक के लिए जाँच की जाती है?

निष्कर्ष

डॉक्स-ए-कोड "पोस्ट-फैक्ट नोट्स" से दस्तावेज़ीकरण को विकास की एक कार्यशील कलाकृति में बदल देता है: छंटनी, परीक्षण और वितरित। इस दृष्टिकोण के साथ, ज्ञान कोड के बगल में रहता है, परिवर्तन पारदर्शी होते हैं, और उपयोगकर्ताओं और इंजीनियरों को आवश्यकता होने पर अप-टू-डेट निर्देश, आरेख और उदाहरण प्राप्त होते हैं। यह परिचालन जोखिमों को कम करता है, ऑनबोर्डिंग को गति देता है और पूरे प्लेटफॉर्म में समाधान की गुणवत्ता में सुधार