Τεκμηρίωση ως κωδικός

1) Αρχιτεκτονικές αρχές

1. Μια μοναδική πηγή αλήθειας. Έγγραφα, διαγράμματα, διαγράμματα, προδιαγραφές API, γλωσσάριο - σε VCS δίπλα στον κωδικό.
2. Αυτόματος έλεγχος ποιότητας. Linters, ορθογραφία, έλεγχος συνδέσμων, παραδείγματα κώδικα doctest.
3. Συναρμολόγηση ως τεχνούργημα. Τόπος σύνδεσης, PDF/ebook, «ενσωματωμένες υποδείξεις» - μέρος του αγωγού απελευθέρωσης.
4. Εκδοχή και ιχνηλασιμότητα. Doc κανόνες το ίδιο PR που αλλάζει τη συμπεριφορά του συστήματος? Οι ADR δεσμεύονται.
5. Διαθεσιμότητα ανά ρόλο. Δημόσιες/εσωτερικές, Runbook 'και εφημερίες, API specs για τους ενοποιητές.
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 - Συζήτηση λύσεων πριν από την εφαρμογή.
• ΕΕΔ - σταθερή αρχιτεκτονική λύση (πλαίσιο → λύση → συνέπειες → εναλλακτικής λύσης).
• Runbook/Playbook - οδηγίες βήμα προς βήμα για περιστατικά και πτητικές λειτουργίες.
• Πώς να/Συχνές ερωτήσεις - εργασία → βήματα → τον έλεγχο του αποτελέσματος.
• API specs - OpenAPI/AsyncAPI/Proto ως πηγή παραγωγής και αποβάθρας SDK.
• Διαγράμματα ως κωδικός - Mermaid/PlantUML/Graphviz/C4.

3) Στυλ και πρότυπα

Οδηγός ενιαίου στυλ (τόνος, ορολογία, πρότυπα τίτλου, παραδείγματα).
Γλωσσάριο με κανονικούς όρους (EN/RU), ψευδώνυμα, απαγορευμένα σκευάσματα.
Αρίθμηση και παραπομπές: μόνιμες άγκυρες, διασταυρώσεις μεταξύ ADR/RFC/κωδικού.

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

4) Συνέλευση και δημοσίευση

• MkDocs (Υλικό) - απλή, βολική, καλή πλοήγηση και αναζήτηση.
• Docusaurus - έκδοση τεκμηρίωσης και docs + blog; Συστατικά MDX.
• Antora - αρθρωτή τεκμηρίωση για μεγάλες πλατφόρμες.

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) Ποιότητα: πτερύγια και δοκιμές τεκμηρίωσης

• Markdownlint - Κανόνες μορφοποίησης Markdown.
• Vale - στυλ/ορολογία/τόνος.
• Ορθογραφία (λεξικά RU/EN).
• Σύνδεσμος - εξωτερικοί/εσωτερικοί σύνδεσμοι, άγκυρες.
• Doctest/Παραδείγματα - snippets κώδικα εκτέλεσης, συγχρονίζοντας εκδόσεις CLI/API.
• Σχεδιασμός - OpenAPI/AsyncAPI/JSON Schema/Proto επικύρωση.

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 docs/snippets/calc. py '.

7) Διαδικασίες: RFC/ADR/Reviews και SLA για την απαρχαίωση

Ροή RFC: ο εκκινητής σχέδιο αντιγράφου συζήτησης απόφασης σχεδιάζει την εφαρμογή retro post facto.
Ροή ADR: καθορίστε εν συντομία την επιλογή + αναφορά σε RFC/πειράματα.
Διαδικασίες αναθεώρησης: πηγή - "CODEOWNERS" + "doc-owners. yaml '.
SLA για την απαξίωση: τα κρίσιμα άρθρα έχουν «τελευταία _ αναθεώρηση» και προειδοποίηση για επανεξέταση σε 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/< τοπική>'.
Κλειδιά και πλαίσιο: αποθήκευση «σταθερής ταυτότητας» για κεφαλίδες/θραύσματα.
Έλεγχοι: βαθμιδωτά «πλήκτρα που λείπουν», προειδοποιήσεις για αποσυγχρονισμό.
Τοπικά στυλ: τοπικά γλωσσάρια, άκυρο χαρτί εντοπισμού, παραδείγματα κώδικα στην τοπική γλώσσα UI.

9) Ενοποίηση προϊόντων

Ενσωματωμένη βοήθεια (in-app docs): συστατικά MDX, ενδείξεις πλαισίου.
Έκδοση με έκδοση: tags/branches 'docs/vX. Y ', μια ιστοσελίδα με εκδόσεις επιλογέα.
Αυτόματη δημιουργία τμημάτων: από OpenAPI/AsyncAPI, GraphQL SDL, CLI '-help'.
Changelog ως κωδικός: αυτόματη παραγωγή με ετικέτες δημοσίων σχέσεων (feat/fix/docs/breaking).

10) Μετρήσεις και παρατηρησιμότητα της τεκμηρίωσης

Docs SLO: κατασκευή/δημοσίευση χρόνου, ώρα ανόδου της τοποθεσίας, ώρα εμφάνισης του εγγράφου μετά τις δημόσιες σχέσεις.
Κάλυψη αντικειμένων: μερίδιο υπηρεσιών με ADR, μερίδιο τελικών σημείων με παραδείγματα, μερίδιο των Runbooks με «υγειονομικούς ελέγχους».
Μετρήσεις χρηστών: αναπάντητες αναζητήσεις, βάθος προβολής, CTR ενσωματωμένων κινήτρων.
Ποιότητα: σφάλματα χιτωνίων/1000 γραμμές, «σπασμένοι σύνδεσμοι», το ποσοστό των παρωχημένων ειδών.

11) Ασφάλεια και ιδιωτικότητα

Τα μυστικά και το PD απαγορεύονται στις συμφωνίες επαναγοράς. συνδέσεις για μυστικά και συγκάλυψη.
Πρόσβαση στην εσωτερική τοποθεσία μέσω SSO· διαχωρισμένα δημόσια τμήματα.
Κανόνες εξαγωγής: PDF/αρχεία χωρίς εσωτερικούς συνδέσμους, υδατογραφήματα για εμπιστευτικά έγγραφα.
Υγιεινή στιγμιότυπου οθόνης: αυτόματη ανωνυμοποίηση (mok data/blur).

12) Πρότυπα

Γιατροί στις δημόσιες σχέσεις. Κάθε αλλαγή που επηρεάζει τη συμπεριφορά περιλαμβάνει την επικαιροποίηση των δεξαμενών στην ίδια ΠΚ.
Υποδείγματα ως σύμβαση. Δημιουργία υπηρεσίας/τελικού σημείου/συνόλου δεδομένων - μέσω μιας γεννήτριας που βάζει κενά στη δεξαμενή.
Διαγράμματα ως κωδικός. Οποιαδήποτε εικόνα - επεξεργάσιμη πηγή, συγκρότημα SVG/PNG σε CI.
Προεπισκόπηση εγγράφων. Σχόλιο Bot με σύνδεση με προεπισκόπηση τοποθεσίας για δημόσιες σχέσεις.
Σύνδεσμοι σύνδεσης στον κώδικα. Σημειώσεις σε πηγές ('@ doc: adr/0007') που δίνονται στην ιστοσελίδα.

13) Αντι-μοτίβα

Τεκμηρίωση σε wiki/Notion χωρίς εκδόσεις δίπλα στον κώδικα → εκτός συγχρονισμού.
Στιγμιότυπα οθόνης χωρίς πηγές → αδυναμία αυτόματης ενημέρωσης.
«Μυστικές» γνώσεις σε προφορικές συνομιλίες και ιδιωτικά αρχεία.
Γενόσημα χωρίς παραδείγματα και αναλλοίωτα → άχρηστες σελίδες.
Η έλλειψη ιδιοκτητών και η «τελευταία _ αναθεώρηση» → χιονοστιβάδα της απαξίωσης.
Η χειροκίνητη συναρμολόγηση και δημοσίευση → εύθραυστη και σπάνια απελευθέρωση αποβάθρων.

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. Συμπεριλαμβάνονται οι linters (markdownlint, Vale), ο ορθογραφικός έλεγχος, ο linkcheck και ο doctest

4. Διαγράμματα και διαγράμματα - όπως κώδικας, συναρμολόγηση σε CI

5. Επικυρώνονται και παρέχονται στον ιστότοπο οι προδιαγραφές API (OpenAPI/AsyncAPI/Proto)

6. Οργανωμένο docs-preview για δημόσιες σχέσεις και αυτόματη δημοσίευση με συγχώνευση

7. Υπάρχουν παλαιές SLA (last_review) και «ιδιοκτήτες» σελίδων

8. Μετρήσεις: κάλυψη, σφάλματα γραμμής, σπασμένοι σύνδεσμοι, αναζήτηση «μηδενικών» ερωτήσεων

9. Πολιτικές ασφάλειας: απαγορευμένα μυστικά, SSO, υδατογραφήματα/εξαγωγές

10. Η τοπικοποίηση ελέγχεται από υποκαταστήματα και ελέγχεται για παραλείψεις

Συμπέρασμα

Το Docs-as-Code μετατρέπει την τεκμηρίωση από «σημειώσεις μετά-γεγονός» σε ένα τεχνούργημα ανάπτυξης εργασίας: μεταφρασμένο, δοκιμασμένο και παραδοθέν. Με αυτή την προσέγγιση, η γνώση ζει δίπλα στον κώδικα, οι αλλαγές είναι διαφανείς και οι χρήστες και οι μηχανικοί λαμβάνουν ενημερωμένες οδηγίες, διαγράμματα και παραδείγματα όταν χρειάζονται. Αυτό μειώνει τους λειτουργικούς κινδύνους, επιταχύνει την επιβίβαση και βελτιώνει την ποιότητα των λύσεων σε ολόκληρη την πλατφόρμα.