תיעוד כקוד

1) עקרונות אדריכליים

1. מקור אחד של אמת. מסמכים, תרשימים, תרשימים, מפרט API, גלוסרי - ב VCS ליד הקוד.
2. בדיקת איכות אוטומטית. לינטרס, איות, בדיקת קישור, דוגמאות קוד doctest.
3. הרכבה כחפץ. אתר עגינה, PDF/Ebook, ”רמזים מובנים” - חלק מצינור השחרור.
4. ורסינינג ויכולת איתור. דוק שולט באותו יחסי ציבור שמשנה את ההתנהגות של המערכת; ADRs מחויבים.
5. זמינות לפי תפקיד. ציבורי/פנימי, רנבוק 'ו תורן, מפרט API לאינטגרטורים.
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 - לדון פתרונות לפני יישום.
• ADR - פתרון ארכיטקטוני קבוע (context _ solution _ group of late alternative).
• רינון/ספר משחקים - הוראות צעד אחר צעד לתקריות ופעולות.
• How-To/FAQ - שלבי Gast # לבדוק את התוצאה.
• מפרט API - OpenAPI/ASyncAPI/Proto כמקור לדורות ורציפים של SDK.
• תרשימים כקוד - Mermaid/PlantUML/Graphviz/C4.

3) סגנון וסטנדרטים

מדריך סגנון יחיד (טון, מינוח, תבניות כותרת, דוגמאות).
גלוסרי עם מונחים קנוניים (EN/RU), כינויים, נוסחאות אסורות.
מספר והפניות: עוגנים קבועים, צירוף אזכורים בין ADR/RFC/code.

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 מועברים לאתר; SDK/לקוחות/דוגמאות מופקות מהם.

6) איכות: תיקונים ומבחני תיעוד

• סמן - Markdown פורמט כללים.
• Vale - סגנון/מינוח/טון.
• בדיקת כתיב - איות (מילונים RU/EN).
• לינקצ 'ק - קישורים חיצוניים/פנימיים, עוגנים.
• Doctest/דוגמאות - ביצוע קטעי קוד, סינכרון גרסאות CLI/API.
• סכימה - OpenAPI/ASYncAPI/JSON Schema/Proto validation.

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

CI רץ 'Python-m doctest docos/sbippets/calc. פיי '.

7) תהליכים: RFC/ADR/ביקורות ו ־ SLAs להתיישנות

זרימת RFC: ייזום = trapt process ac.view # program # program * retro post facto.
זרימת ADR: לתקן בקצרה את הבחירה + התייחסות RFC/ניסויים.
נוהלי סקירה: מקור - 'CODEOWERS' + 'doc-הבעלים. יאמל '.
SLA להתיישנות: במאמרים ביקורתיים יש 'last _ review' וערנות לסקירה בימים N.

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> ".
מפתחות והקשר: לאחסן ”זיהוי יציב” עבור כותרות/שברים.
צ 'קים: צעד ”חסר-מפתחות”, התראות לדיסינכרונציה.
סגנונות לוקאלה: גלוסריות מקומיות, נייר איתור לא תקף, דוגמאות של קוד בשפת UI המקומית.

9) שילוב מוצר

עזרה מובנית (ב-application docs): רכיבי MDX, רמזי הקשר.
ויסות על ידי שחרור: תגיות/סניפים 'docs/vX. אתר עם גרסאות סלקטור.
דור אוטומטי של קטעים: מ ־ OpenAPI/AsyncAPI, GraphQL SDL, CLI '-help'.
Changelog כקוד: דור אוטומטי על ידי תוויות יחסי ציבור (feat/fix/docs/breaking).

10) מדדים ויכולת תצפית בתיעוד

Docs SLO: לבנות/לפרסם זמן, אתר למעלה, זמן הופעת מסמך לאחר יחסי ציבור.
כיסוי חפצים: שיתוף שירותים עם ADRs, שיתוף נקודות קצה עם דוגמאות, שיתוף של Runbooks עם ”בדיקות בריאות”.
מדדי משתמש: חיפושים ללא מענה, עומק צפייה, CTR של דואר מובנה.
איכות: שגיאות לינטר/1000 שורות, ”קישורים שבורים”, פרופורציה של מאמרים מיושנים.

11) ביטחון ופרטיות

סודות ומשטרה אסורים בשידורים חוזרים; מקשרים לסודות ומסכות.
גישה לאתר הפנימי באמצעות SSO; חלקים ציבוריים מופרדים.
כללי ייצוא: PDF/ארכיון ללא קישורים פנימיים, סימני מים עבור מסמכים חסויים.
תברואה צילום מסך: אנונימיות אוטומטית (mok data/talur).

12) תבניות

רופאים ביחסי ציבור. כל שינוי שמשפיע על התנהגות כרוך בעדכון הרציפים באותו יחסי ציבור.
תבניות כחוזה. יצירת שירות/אנד פוינט/נתונים באמצעות גנרטור ששם כדורי מזח.
תרשימים כקוד. כל מקור ראוי לעריכה, SVG/PNG ב CI.
Docs תצוגה מקדימה. הערת בוט עם קישור לתצוגה מקדימה עבור יחסי ציבור.
קישורי עגינה בקוד. אנוטציות במקורות (”@ doc: adr/0007”) שמועברות לאתר.

13) אנטי דפוסים

תיעוד בוויקי/רעיון ללא גרסאות ליד הקוד.
צילומי מסך ללא מקורות = חוסר היכולת לעדכן באופן אוטומטי.
ידע ”סודי” בשיחות בעל פה וקבצים פרטיים.
Generics ללא דוגמאות ו invariants = דפים חסרי תועלת.
מחסור בבעלים ו 'סקירה' אחרונה. מפולת שלגים של התיישנות.
הרכבה ופרסום ידני = שחרור רגיש ונדיר של רציפים.

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. לינטרס כולל (markdownlint, Vale), בדיקת איות, לינקצ 'ק ומבחן?
4. תרשימים ודיאגרמות - כמו קוד, הרכבה במודיע?
5. האם מפרט API (OpenAPI/ASyncAPI/Proto) קיבל תוקף לאתר?
6. תצוגה מקדימה של רופאים מאורגנים ליחסי ציבור ופרסום אוטומטי על ידי מיזוג?
7. האם ישנם סלאחים מזדקנים (last_review) ו ”בעלים” של דפים?
8. מטריצות: כיסוי, שגיאות לינטר, קישורים שבורים, חיפוש שאילתות ”אפס”?
9. מדיניות ביטחון: סודות אסורים, SSO, סימני מים/יצוא?
10. לוקליזציה נשלטת על ידי סניפים ונבדק להשמטות?

מסקנה

Docs-as-Code הופך את התיעוד מ ”הערות פוסט-עובדות” לחפץ עבודה של פיתוח: עם גישה זו, ידע חי לצד הקוד, שינויים הם שקופים, ומשתמשים ומהנדסים מקבלים הוראות עדכניות, תרשימים ודוגמאות בעת הצורך. זה מפחית סיכונים מבצעיים, מאיץ את העלייה למטוס ומשפר את איכות הפתרונות על פני הפלטפורמה.