ഡോക്സിനും റൺബുക്കുകളും ആളുകൾ വായിക്കുന്നുണ്ട്.

എല്ലാ ടീമുകളും ഡോക്യുമെന്റേഷന് വിലമതിക്കുന്നു. പിന്നെ വിക്കി തുറന്ന് മൂന്ന് വർഷം മുമ്പ് അപ്ഡേറ്റ് ചെയ്ത പേജുകൾ കാണും, നിലവിലില്ലാത്ത സെർവറുകളുടെ നിർദ്ദേശങ്ങൾ, 2023 ൽ പോയ ഒരാളുടെ "TODO: write this" എന്ന പേജ്.

മോശം രേഖകളാണ് ഒന്നുമില്ലാത്തതിലും മോശം, കാരണം ആളുകൾ അവയെ വിശ്വസിക്കുകയും അവയെ പിന്തുടരുകയും ചെയ്യുന്നു. പക്ഷെ നല്ല ഡോക്യുമെന്റേഷൻ ഒരു DevOps ടീമിന് ഉല്പാദിപ്പിക്കാവുന്ന ഏറ്റവും ഉയർന്ന ലിവറേജ് ഉള്ള കാര്യമാണ്. അവധിദിനങ്ങളെയും രോഗദിനങ്ങളേയും ആളുകൾ മുന്നോട്ട് പോകുന്നതിലും അറിവ് അതിജീവിക്കുന്നത് ഇങ്ങനെയാണ്.

ഇവിടെ ഉപയോഗപ്രദമായി നിലനിൽക്കുന്ന ഡോക്യുമെന്റേഷനുകൾ എഴുതുന്നതെങ്ങനെ എന്ന് കാണിക്കുന്നു.

ഡോക്ടർമാർ ചീഞ്ഞുവീഴുന്നത് എന്തിനാണ്?

• അവര് കോഡില് നിന്ന് വളരെ അകലെ താമസിക്കുന്നു. സിസ്റ്റം മാറ്റുമ്പോള് ആരും നോക്കാത്ത വിക്കി.
• അവയൊന്നും ആരുടേയും സ്വന്തമല്ല. എല്ലാവരും എഡിറ്റ് ചെയ്യാം, അതുകൊണ്ട് ആരും ഉത്തരവാദിത്തം അനുഭവിക്കുന്നില്ല.
• അവരും ഈ ജോലിയുടെ ഭാഗമല്ല. ഡോക്യുമെന്ററി അധികമാണ്, പിന്നീട് ചെയ്താൽ മതി, അതായത് ഒരിക്കലും.
• അവ വളരെ നീണ്ടതാണ്. ആളുകൾ വായിച്ചു കളയുന്നു, പ്രധാനപ്പെട്ട ഭാഗം കാണാതെ പോകുന്നു, പിന്നെ വായിക്കുന്നത് നിർത്തുന്നു.

ഡോക്റ്റർമാര് കോഡിന്റെ അടുത്താണ് താമസിക്കുന്നത്.

ഡോക്സിംഗ് കോഡ് രേഖകള് കോഡായി കണക്കാക്കുക എന്നാണ് അർത്ഥം.

• എഴുതിയത് മാർക്കഡൌൺ, ഒരേ റിപ്പോസിറ്ററി അവര് വിവരിച്ച കോഡായി.
• പരിഷ്കരിച്ച ഒരേ വലിച്ചെടുക്കൽ അഭ്യർത്ഥന കോഡ് മാറുന്നതോടെ.
• അവലോകനം ഒരു കോഡ് പോലെ.
• സ്വയം പ്രസിദ്ധീകരിച്ചു ഒരു നല്ല വെബ്സൈറ്റിലേക്കുള്ള ഒരു പൈപ്പ്ലൈൻ വഴി.

ഇത് എളുപ്പമാക്കുന്ന ഉപകരണങ്ങള്:

• എം. കെ. ഡോക് കൂടെ വസ്തുക്കൾ വിഷയം: ലളിതവും മനോഹരവും സാങ്കേതിക രേഖകൾക്കായി വളരെ പ്രചാരമുള്ളതുമാണ്.
• ഡോക്സൌറസ്: വലിയ ഡോക്യുമെന്റേഷൻ സൈറ്റുകൾക്ക് അനുയോജ്യമായ, റിയാക്ട് അടിസ്ഥാനമാക്കിയുള്ളതാണ്.
• തിരശ്ശീലയിലെ ടെക് ഡോക്കുകൾ: നിങ്ങളുടെ ഡെവലപ്പർ പോർട്ടലിനുള്ളിലെ ഓരോ റിപ്പോസിറ്ററിയിൽ നിന്നും MkDocs ഡോക്കുകൾ റാൻഡർ ചെയ്യുന്നു.
• പ്ലെയിൻ README.md എന്ന താളിൽ നിന്നും ഗിറ്റ്ഹബ്, ഗിറ്റ്ലാബ് എന്നിവയും നന്നായി റെൻഡർ ചെയ്യുന്നു.

"ഡോക്യുമെന്റേഷൻ അപ്ഡേറ്റ് ചെയ്തു (അല്ലെങ്കിൽ ആവശ്യമില്ല) " എന്ന ചെക്ക്ബോക്സുള്ള ഒരു പിൻ അഭ്യർത്ഥന ടെംപ്ലേറ്റ് വളരെ സഹായകരമാണ്.

ഡോക്യുമെന്റേഷൻ അപ്ഡേറ്റ് ചെയ്യാനുള്ള ഏറ്റവും നല്ല സമയം തെറ്റായ ഒരു പിൾ അഭ്യർത്ഥനയിലായിരിക്കും.

ഒരു റൺബുക്ക് ടെംപ്ലേറ്റ്

ഓപ്പറേഷന് റെ ഏറ്റവും പ്രധാനപ്പെട്ട രേഖകളാണ് റൺബുക്കുകൾ. രാവിലെ 3 മണിക്ക് ഒരു അലാറം തുടങ്ങുമ്പോൾ, ഡിറ്റര് ണിംഗ് എഞ്ചിനീയര് ക്ക് പെട്ടെന്ന് ഉത്തരം വേണം, പ്രസയല്ല.

എന്റെ ടെംപ്ലേറ്റ്:

# Alert: CheckoutHighErrorRate

## What it means
More than 2% of checkout requests return 5xx errors over 5 minutes.

## Impact
Customers can't complete purchases. Revenue impact. Treat as SEV2 or higher.

## Check
1. Dashboard: [Checkout overview](https://grafana.example.com/d/checkout)
2. Recent deployments: `kubectl rollout history deploy/checkout -n shop`
3. Errors by endpoint: [Logs query](https://grafana.example.com/explore?...)
4. Payment provider status: https://status.paymentprovider.example

## Common causes and fixes
- **Bad deployment** → roll back: revert the commit in the GitOps repo
  (or `kubectl rollout undo deploy/checkout -n shop` in an emergency).
- **Payment provider outage** → switch to backup provider via feature flag `payments.fallback`.
- **Database connection exhaustion** → check `orders-db` connections dashboard; scale checkout down
  temporarily or restart the connection pooler.

## Escalation
- Checkout team: @checkout-oncall
- Database: @dba-oncall
- Incident commander for SEV1: use `/incident declare`

## Last reviewed
2026-09-15 by @desly

പ്രധാന തത്വങ്ങള്: നേരിട്ട് ലിങ്ക് ചെയ്യുക ഡാഷ്ബോർഡുകളിലും ചോദ്യങ്ങളിലും, കോപ്പി-പേസ്റ്റ് കമാൻഡുകൾ, പട്ടിക സാധാരണ കാരണങ്ങൾ ആദ്യംഎന്നിട്ട് പറയൂ ആരെയാ വിളിക്കേണ്ടത്?. ആ അലേർട്ടിന്റെ റൺബുക്ക് ബന്ധിപ്പിക്കുക.

തീരുമാനങ്ങള് രേഖപ്പെടുത്തുക

ആറുമാസം കഴിഞ്ഞിട്ടും ആരും തീരുമാനമെടുത്തത് എന്തിന് എന്ന് ഓർക്കുന്നില്ല. "എന്തുകൊണ്ടാണ് നമ്മൾ ലോക്കി ഉപയോഗിക്കുന്നത്, എലാസ്റ്റിക് സെർച്ച് അല്ലെ?" "എന്തുകൊണ്ട് ഈ സേവനം സ്വന്തം ക്ലസ്റ്ററിൽ ഉണ്ട്?" ഒരു റെക്കോർഡ് ഇല്ലാതെ, ടീമുകൾ പഴയ ചർച്ചകൾ ആവർത്തിക്കുകയോ അല്ലെങ്കിൽ നല്ല തീരുമാനങ്ങൾ അബദ്ധത്തിൽ അസാധുവാക്കുകയോ ചെയ്യുന്നു.

വാസ്തുവിദ്യാ തീരുമാന രേഖകൾ (ADRs) ഇത് പരിഹരിക്കൂ. ഒരു എ ഡി ആർ എന്നത് ഒരു ചെറിയ രേഖയാണ്, സാധാരണയായി ഒരു പേജ്, റിപ്പോസിറ്ററിയിൽ സൂക്ഷിക്കുന്നുഃ

# ADR-012: Use Gateway API instead of Ingress for new services

## Status
Accepted (2026-05-04)

## Context
ingress-nginx was retired in March 2026. We need a supported way to route traffic.

## Decision
New services use Gateway API with Envoy Gateway. Existing Ingress resources
are migrated by end of Q3.

## Consequences
+ Supported, portable API with role separation.
- Teams need to learn HTTPRoute; some annotations need manual migration.

നമ്പറുകളുള്ളതും ചുരുക്കിയതും ഒരിക്കലും മായ്ച്ചിട്ടില്ലാത്തതുമായ (അവസാനിപ്പിച്ച ADR- കൾ അങ്ങനെ അടയാളപ്പെടുത്തിയിരിക്കുന്നു). ഉപകരണങ്ങൾ അഡ്രി-ടൂളുകൾ അല്ലെങ്കില് ലോഗ്4ബ്രെയിൻസ് സഹായിക്കാന് , പക്ഷെ മാർക്ക് ഡൌൺ ഫയലുകളുടെ ഒരു ഫോൾഡര് തികച്ചും ശരിയാണ്.

അത് പുതുതായി സൂക്ഷിക്കുക

• ഉടമസ്ഥർ: ഓരോ ഡോക്യുമെന്ററിനും അല്ലെങ്കിൽ ഫോൾഡറിനും ഒരു ഉടമസ്ഥ സംഘമുണ്ട് (കോഡ് ഉടമസ്ഥർ ഡോക്യുമേന്ററിനും വേണ്ടി പ്രവർത്തിക്കുന്നു).
• "അവസാനമായി അവലോകനം ചെയ്ത" തീയതികൾ റൺബുക്കുകളില് പതിവായി അവലോകനം ചെയ്യപ്പെടുന്നു (ഉദാഹരണത്തിന്, ഓരോ ക്വാർട്ടിലും, അല്ലെങ്കിൽ റൺബുക്ക് ഉപയോഗിച്ച ഓരോ സംഭവത്തിനും ശേഷം).
• സംഭവത്തിനു ശേഷമുള്ള അപ്ഡേറ്റ്: മരണാനന്തര പ്രവർത്തനങ്ങളുടെ ഒരു ഇനം പലപ്പോഴും "റൺബുക്ക് അപ്ഡേറ്റ് ചെയ്യുക" ആണ്.
• ആക്രമണാത്മകമായി ഇല്ലാതാക്കുകകാലഹരണപ്പെട്ട രേഖകൾ അപകടകരമാണ്. അവയെ ആര് ഷിഫ് ചെയ്യുകയോ ഇല്ലാതാക്കുകയോ ചെയ്യുക.
• അത് ചുരുക്കമായിരിക്കട്ടെ.ഒരു വ്യക്തമായ പേജ് പത്ത് അവ്യക്തമായ പേജുകളെ മറികടക്കുന്നു.
• അത് തിരയാവുന്നതാക്കുക: തിരയലുള്ള ഒരു ഡോക് സൈറ്റ്, അല്ലെങ്കിൽ ബാക്ക്സ്റ്റേജ് പോലുള്ള ഒരു പോർട്ടൽ.

എഐയെ കുറിച്ചുള്ള ഒരു വാക്ക്

ഡോക്യുമെന്റേഷൻ തയ്യാറാക്കുന്നതില് AI ഉപകരണങ്ങള് വളരെ നല്ലതാണ്: ഒരു കോഡ്ബേസ് സംഗ്രഹിക്കുക, ഒരു സംഭവത്തിന്റെ ടൈംലൈനിനെ ഒരു റൺബുക്കാക്കി മാറ്റുക, സങ്കീർണ്ണമായ കോൺഫിഗറേഷന് വിശദീകരിക്കുക. ആദ്യ ഡ്രാഫ്റ്റിനായി ഉപയോഗിക്കുക. പക്ഷെ സിസ്റ്റം അറിയുന്ന ഒരു മനുഷ്യന് ഓരോ ചുവടും പരിശോധിക്കേണ്ടതുണ്ട്, കാരണം തെറ്റായ റൺബുക്ക് രാവിലെ 3 മണിക്ക് ഒന്നുമില്ല എന്നതിനേക്കാൾ മോശമാണ്.

എവിടെ നിന്നാണ് ഞാൻ തുടങ്ങേണ്ടത്?

മുകളിലുള്ള ടെംപ്ലേറ്റിനൊപ്പം നിങ്ങളുടെ ഏറ്റവും പതിവ് അഞ്ച് അലേർട്ടുകൾക്കായി റൺബുക്കുകൾ എഴുതുക, അവ അലേർട്ടിൽ നിന്ന് ലിങ്കുചെയ്യുക. പിന്നെ ഒരു ADR ഫോൾഡർ തുറന്ന് നിങ്ങളുടെ ടീം എടുക്കുന്ന അടുത്ത തീരുമാനത്തെക്കുറിച്ച് ആദ്യത്തെ റെക്കോർഡ് എഴുതുക.

എന്റെ അഭിപ്രായം: ഡോക്യുമെന്റേഷൻ നിങ്ങളുടെ ഭാവിയിലേക്കുള്ള സമ്മാനമാണ്, നിങ്ങളുടെ സഹപ്രവർത്തകർക്കും. അത് കോഡിനോട് ചേര് ന്ന്, ചുരുക്കമായി, സത്യസന്ധമായി സൂക്ഷിക്കുക.

ഡെസ്ലി