डॉक्युमेंटेशन रॉट: इंजीनियरिंग विकी 6 माह में क्यों मरती है
इंजीनियरिंग विकी जल्दी खराब होती हैं। यह फोरेंसिक टाइमलाइन दिखाती है कि डॉक्युमेंटेशन रॉट कैसे शुरू होती है और कौन से सिस्टम इसे वास्तव में रोकते हैं।
By Ellis Keane · 2026-04-07
हर इंजीनियरिंग टीम के पास एक Notion वर्कस्पेस (या Confluence इंस्टेंस, या GitHub विकी, या जो भी डॉक्युमेंटेशन टूल टीम की स्थापना के साल फैशन में था) होता है जिसमें "Service Architecture Overview" जैसी कोई पेज होती है – जिसे आखिरी बार ग्यारह महीने पहले किसी ऐसे व्यक्ति ने एडिट किया था जो अब वहाँ काम नहीं करता। वह पेज डॉक्युमेंटेशन नहीं है, वह एक जीवाश्म है – और जो डॉक्युमेंटेशन रॉट उसे जीवाश्म बनाई, वह उसके लिखे जाने के अगले दिन से शुरू हो गई थी, यानी उसी दिन जब सभी ने सहमति जताई कि "इसे अप-टू-डेट रखना सच में बहुत ज़रूरी है।"
विकी पेज जमी रहती है जबकि उसके आसपास सब कुछ बदलता रहता है। कोई इसे डिलीट नहीं करता क्योंकि डिलीट करना विनाशकारी लगता है। कोई इसे अपडेट नहीं करता क्योंकि अपडेट करना किसी और का काम लगता है। तो यह बस वहीं बैठी रहती है, आधिकारिक दिखती है, और धीरे-धीरे कल्पना बन जाती है। attribution: Ellis Keane
हम डॉक्युमेंटेशन रॉट को एक अनुशासन समस्या के रूप में देखते हैं – मानो इंजीनियरों को बस पेजों को अपडेट रखने की अधिक परवाह करने की ज़रूरत हो, मानो असली बाधा प्रेरणा हो, आर्किटेक्चर नहीं। लेकिन जिन टीमों से हम बात करते हैं उनमें (और ईमानदारी से कहें तो हमारे अपने छोटे से ऑपरेशन में भी, जहाँ हम भी इससे अछूते नहीं हैं) इस पैटर्न को बार-बार देखने के बाद, विफलता हमेशा एक ही होती है: docs एक जगह रहते हैं, कोड बदलाव दूसरी जगह होते हैं, और कोई सिस्टम उन्हें जोड़ता नहीं। यह परवाह के बारे में नहीं है। यह उस बुनियादी असंगति के बारे में है जो डॉक्युमेंटेशन के काम करने के तरीके और इंजीनियरिंग के वास्तव में चलने के तरीके के बीच है – और हमें अभी तक उस असंगति का कोई केवल-प्रक्रिया-आधारित समाधान नहीं मिला है, हालाँकि हम कोशिश करते रहते हैं।
एक विकी पेज की फोरेंसिक टाइमलाइन
जो नीचे दिया गया है वह इंजीनियरिंग टीमों के साथ बातचीत और (खेद के साथ) अपने अनुभव से निकला एक संग्रह है, लेकिन यह क्रम इतना लगातार संगठनों में दोहराया जाता है कि विशेष जानकारी शायद ही मायने रखती हो। मुझे बताने दीजिए कि आंतरिक दस्तावेज़ीकरण के एक टुकड़े के साथ वास्तव में क्या होता है – उसके बनाए जाने के क्षण से लेकर उस क्षण तक जब कोई उस पर भरोसा करके गलत फैसला लेता है।
title: "एक विकी पेज कैसे खतरनाक बन गई" दिन 1|ok|एक बड़े रिफैक्टर के बाद एक इंजीनियर "Payment Service Architecture" लिखता है। सटीक, विस्तृत, सीक्वेंस डायग्राम के साथ। दिन 14|ok|दो डेवलपर ऑनबोर्डिंग के दौरान पेज का संदर्भ लेते हैं। इससे उनके घंटों की बचत होती है। पेज सफल लगती है। दिन 31|amber|एक टीम मेंबर payment service में retry logic रिफैक्टर करता है। PR मर्ज होती है। कोई विकी पेज के बारे में नहीं सोचता। दिन 45|amber|टीम shared Postgres इंस्टेंस से dedicated पर जाती है। विकी पेज का database connection सेक्शन अब ऐसे इन्फ्रास्ट्रक्चर का वर्णन करता है जो अब मौजूद नहीं। दिन 72|amber|एक नया इंजीनियर पेज पढ़ता है और documented database config के आधार पर अपना local environment सेट करता है। काम नहीं करता। एक सहकर्मी के कहने पर पता चलता है कि "वह पेज पुरानी है।" तब तक वह पूरी दोपहर debugging में गँवा चुका होता है। दिन 90|missed|रात 2 बजे एक incident आता है। on-call इंजीनियर service का escalation path जानने के लिए विकी पेज देखता है। listed owner ने दो महीने पहले कंपनी छोड़ दी थी। सही व्यक्ति ढूँढने में बीस मिनट बर्बाद होते हैं। दिन 180|missed|छह महीनों में पेज दर्जनों बार देखी गई है। दिन 1 के बाद से एक बार भी एडिट नहीं हुई। हर सेक्शन में कम से कम एक गलती है। किसी को नहीं पता कौन से हिस्से अभी भी सही हैं।
अगर आपने पाँच से अधिक इंजीनियरों की टीम में काम किया है, तो आपने शायद इस टाइमलाइन का कोई न कोई संस्करण जिया होगा – और अगर आप अभी सिर हिला रहे हैं और सोच रहे हैं "इसके लिए हमारे पास एक प्रक्रिया है," तो मैं विनम्रतापूर्वक सुझाव दूँगा कि आप अपनी विकी पर last-modified dates जाँचें। विवरण अलग हो सकते हैं (शायद यह आर्किटेक्चर docs की बजाय API reference है, शायद Notion की बजाय Confluence है, शायद incident 2 बजे की बजाय 3 बजे हुई), लेकिन गिरावट की वक्र हमेशा, ज़िद के साथ, एक जैसी होती है।
"बस docs अपडेट करो" कभी काम क्यों नहीं करता
डॉक्युमेंटेशन रॉट पर सबसे आम प्रतिक्रिया एक प्रक्रिया है: "हमें PR चेकलिस्ट के हिस्से के रूप में docs अपडेट करने चाहिए।" यह उचित लगता है, और हमारे अनुभव में यह अक्सर विफल होता है – ऐसे कारणों से जो इनसेंटिव स्ट्रक्चर को ट्रेस करने पर स्पष्ट हो जाते हैं। जब एक इंजीनियर दिन के अंत से पहले किसी बदलाव को reviewed, merged, और deployed करवाने की कोशिश कर रहा है (और दिन का अंत अपेक्षा से जल्दी आने की आदत रखता है), तो वह docs पेज जो उस component का अस्पष्ट रूप से संदर्भ देती है जिसे उसने अभी बदला – वह बेहतरीन स्थिति में उसके मन के पीछे एक धुंधली जागरूकता है, और सबसे बुरी स्थिति में कुछ ऐसा जिसके बारे में उसे पता ही नहीं। CI pipeline हरी होती है, PR मर्ज होती है, और किसी के वर्कफ़्लो में कोई चरण नहीं है जो कहे "अब जाओ और हर उस विकी पेज को ढूँढो जो पुराने behavior को implicitly assume करती थी।"
और यहाँ वह हिस्सा है जो कोई ज़ोर से नहीं कहना चाहता: भले ही उन्हें पेज याद हो, वे अक्सर नहीं जानते कि विशेष रूप से क्या बदलने की ज़रूरत है। एक कोड बदलाव और उसके दस्तावेज़ीकरण संबंधी निहितार्थों के बीच का संबंध हमेशा स्पष्ट नहीं होता। एक refactored function signature तीन अलग-अलग विकी पेजों को invalid कर सकती है, जिनमें से कोई भी उस function का नाम नहीं लेती।
डॉक्युमेंटेशन रॉट लापरवाही से नहीं होती। यह इसलिए होती है क्योंकि कोड बदलाव और दस्तावेज़ीकरण बदलाव पूरी तरह से अलग-अलग टूल्स में, पूरी तरह से अलग-अलग समय पर, पूरी तरह से अलग-अलग इनसेंटिव संरचनाओं के साथ होते हैं। उनके बीच का संबंध पूरी तरह से मानव स्मृति में बना रहता है – और मानव स्मृति indirect dependencies को ट्रैक करने के लिए एक विश्वसनीय सिस्टम नहीं है।
डॉक्युमेंटेशन रॉट के तीन चरण
दस्तावेज़ीकरण रातोंरात सटीक से खतरनाक नहीं होता – और यही बात इसे इतना कपटी बनाती है। यह तीन अलग चरणों से गुज़रता है, हर एक पिछले से ज़्यादा मुश्किल पहचाने जाने वाला, और किसी भी बिंदु पर किसी को कोई सूचना नहीं मिलती जो कहे "अरे, यह पेज अब लोगों से झूठ बोल रही है।"
पहला चरण है सतही बदलाव (cosmetic drift), जो हफ्तों में शुरू हो जाता है। एक variable name बदलता है, एक URL path अपडेट होता है, एक reorganization के बाद "Owner" फ़ील्ड में किसी टीम मेंबर का नाम गलत हो जाता है। मुख्य जानकारी अभी भी सही दिशा में है, और पेज पढ़ने वाले को सही सामान्य विचार मिलेगा भले ही विशेष जानकारी बदल गई हो। कुछ टूटा हुआ नहीं लगता (और इस बिंदु पर लगभग कभी नहीं लगता), इसलिए कोई कुछ ठीक नहीं करता – क्योंकि cosmetically drifted विकी पेज को ठीक करना flossing के engineering equivalent है: सभी मानते हैं कि यह ज़रूरी है, आज कोई नहीं करता।
फिर आती है संरचनात्मक विचलन (structural divergence), आमतौर पर महीने एक से तीन के बीच, जहाँ आर्किटेक्चर खुद उससे आगे निकल गया है जो पेज वर्णन करती है। शायद service दो services में बँट गई, या एक endpoint deprecated होकर पूरी तरह अलग contract वाले से replace हो गया, या authentication flow पूरी तरह बदल गया। इस चरण में पेज सक्रिय रूप से भ्रामक है, लेकिन यह अभी भी आधिकारिक दिखती है (इसमें diagrams हैं, headings हैं, यह clearly किसी ऐसे व्यक्ति ने लिखा है जो जानता था), इसलिए पाठक उस पर ज़्यादा देर तक भरोसा करते हैं जितना उन्हें करना चाहिए – यही वास्तव में खतरनाक हिस्सा है।
महीने तीन से छह तक, आप खतरनाक कल्पना (dangerous fiction) पर पहुँच जाते हैं। पेज अब ऐसे सिस्टम का वर्णन करती है जो मौजूद नहीं। Listed endpoints 404 return करते हैं। Database schema दो बार migrate हो चुका है। Escalation path उस व्यक्ति तक ले जाती है जो इस समय किसी अन्य कंपनी में काम कर रहा है और शायद यह भी भूल गया कि service कभी थी।
stat: "शून्य बदलाव" headline: "छह महीनों में" source: "इंजीनियरिंग विकी में देखा गया पैटर्न"
इस चरण में डॉक्युमेंटेशन रॉट से होने वाला नुकसान सैद्धांतिक नहीं है। इंजीनियर deployment decisions, incident response decisions, और onboarding decisions ऐसे दस्तावेज़ीकरण के आधार पर लेते हैं जो – सीधे शब्दों में कहें तो – formatting के साथ कल्पना है।
क्या वास्तव में गिरावट को धीमा करता है
यदि प्रक्रिया चेकलिस्ट काम नहीं करतीं (और नहीं करतीं, ऊपर वर्णित संरचनात्मक कारणों से), तो क्या काम करता है? ईमानदार जवाब यह है कि कुछ भी डॉक्युमेंटेशन रॉट को पूरी तरह खत्म नहीं करता, लेकिन कुछ टीमें इसे इतना धीमा करने में कामयाब हो जाती हैं कि एक विकी पेज की half-life हफ्तों से महीनों तक बढ़ जाती है – जो "कभी-कभी भ्रामक" और "सक्रिय रूप से खतरनाक" के बीच का अंतर है। जिन टीमों से हमने बात की है और जो सबसे अच्छा प्रदर्शन करती हैं, उनमें कुछ पैटर्न समान हैं जो जाँचने लायक हैं।
Docs जो code के पास रहते हैं। READMEs repo में, inline comments, Architecture Decision Records (ADRs) जो उनके द्वारा वर्णित code के साथ commit होते हैं। इनका एक स्वाभाविक लाभ है: जब code बदलता है, docs वहीं होते हैं, उसी diff में इंजीनियर को देख रहे होते हैं। इनके अपडेट होने की गारंटी नहीं है (कुछ भी नहीं है), लेकिन proximity अकेले इसे काफी अधिक संभव बनाती है।
स्वचालित पुरानापन पहचान। कुछ टीमें एक सरल स्क्रिप्ट चलाती हैं जो 90 दिनों में edit न हुई किसी भी विकी पेज को flag करती है। यह कच्चा है, लेकिन यह समस्या को चरण 3 से पहले सतह पर लाता है। mechanism सिद्धांत से कम महत्वपूर्ण है: दस्तावेज़ीकरण की सटीकता को ऐसी चीज़ मानें जिसे मापा जा सके, न केवल आशा की जाए।
कम, छोटे दस्तावेज़। 3,000-शब्द की architecture overview, specific components के बारे में तीन focused 500-word pages से ज़्यादा तेज़ी से खराब होगी। छोटी surface area का मतलब है कि हर पेज में कम चीज़ें हो सकती हैं जो गलत हो सकती हैं, और जो व्यक्ति इसे अपडेट रखने का ज़िम्मेदार है, वह पूरी पेज को वास्तव में दिमाग में रख सकता है।
क्या गिरावट को धीमा करता है
- Code के पास docs – READMEs और ADRs repo में, उसी PR में अपडेट
- पुरानापन अलर्ट – 90 दिनों से untouched पेजों के लिए automatic flags
- छोटी, focused पेजें – रॉट के लिए कम surface area
क्या मदद नहीं करता
- PR checklists – "Docs अपडेट करो" checkbox बिना action के tick होती है
- Documentation sprints – एक हफ्ते के updates जो एक महीने में खराब हो जाते हैं
गहरी समस्या: दस्तावेज़ीकरण एक snapshot है, काम एक stream है
ऊपर के सभी समाधान mitigation हैं – और हमें इसके बारे में ईमानदार होना चाहिए। मूल समस्या यह है कि दस्तावेज़ीकरण, अपनी प्रकृति से, किसी ऐसी चीज़ का एक समय-बिंदु snapshot है जो लगातार बदलती रहती है, और कितनी भी process layering इस मूलभूत तनाव को नहीं बदलती। आप आज सिस्टम कैसा है यह लिखते हैं, कल सिस्टम अलग होता है, और दस्तावेज़ीकरण पहले से खराब हो रहा होता है, और कोई तब तक नहीं देखेगा जब तक कोई जल न जाए।
जो टीमें इस समस्या से सबसे कम लड़ती हैं (और हम अभी भी समझ रहे हैं कि "सबसे कम" कैसा दिखता है, ईमानदारी से, क्योंकि किसी ने इसे सच में हल नहीं किया है) वे हैं जो static documentation से living, queryable context की ओर बढ़ गई हैं। "payment service platform team की है" लिखने के बजाय, उनके पास ऐसे tools हैं जो यह सवाल जवाब दे सकते हैं "हाल ही में payment service पर कौन काम कर रहा था?" – actual commits, PRs, और Slack threads देखकर जहाँ असली निर्णय हुए थे।
ठोस रूप से, इसका मतलब है CODEOWNERS और हाल के commit authors से derived ownership, CI से pulled deployment history, pager logs से looked up incident responders, और linked Linear issues और Slack threads के माध्यम से traced decision context। यह कोई wiki नहीं है, और यह उस शब्द के पारंपरिक अर्थ में knowledge management नहीं है। यह एक living index है जो current रहता है क्योंकि यह उन tools से draw करता है जिनका उपयोग लोग पहले से कर रहे हैं – बजाय उनसे एक अलग artifact maintain करने के लिए कहने के जो (अनिवार्य रूप से, predictably) खराब हो जाएगा।
सबसे विश्वसनीय दस्तावेज़ीकरण वह है जो किसी को लिखना नहीं पड़ता। जब context उन tools से pull किया जाता है जहाँ वास्तव में काम होता है (code repos, issue trackers, communication channels), यह बहुत धीरे खराब होता है, क्योंकि यह वास्तव में क्या हो रहा है इसे reflect करता है – न कि किसी ने क्या लिखना याद किया।
जब आपको वास्तव में पारंपरिक docs की ज़रूरत होती है
इसका मतलब यह नहीं कि wikis बेकार हैं। दस्तावेज़ीकरण की specific categories हैं जो वास्तव में एक मानव द्वारा लिखे जाने, जानबूझकर रखरखाव और prose के रूप में संग्रहीत होने से लाभान्वित होती हैं:
- Onboarding guides जो architectural decisions के पीछे का "क्यों" explain करते हैं – सिर्फ "क्या" नहीं
- Runbooks incident response के लिए, जहाँ audience रात 2 बजे का stressed इंजीनियर है जिसे checklist चाहिए, नॉलेज ग्राफ़ query नहीं
- Compliance documentation auditors द्वारा required जो structured, versioned artifacts की expect करते हैं
- Public API references external developers द्वारा consumed
मुख्य अंतर: ये documents ऐसी चीज़ें describe करते हैं जो धीरे बदलती हैं (company values, compliance requirements, public contracts) या ऐसी चीज़ें जहाँ narrative context current accuracy से ज़्यादा matter करता है (तीन साल पहले हमने DynamoDB पर Postgres क्यों चुना)।
बाकी सब के लिए (कौन क्या own करता है, current architecture क्या है, वह decision कहाँ हुआ), जवाब वह विकी पेज नहीं होनी चाहिए जो किसी ने छह महीने पहले लिखी। यह उसके खिलाफ एक query होनी चाहिए जो वास्तव में हुआ।
सिग्नल इंटेलिजेंस सीधे अपने इनबॉक्स में पाएँ।
अक्सर पूछे जाने वाले सवाल
Q: इंजीनियरिंग टीमों में डॉक्युमेंटेशन रॉट क्या है? A: डॉक्युमेंटेशन रॉट समय के साथ आंतरिक दस्तावेज़ीकरण की सटीकता में धीरे-धीरे होने वाली गिरावट है। जो पेज लिखते समय सही थे, वे भ्रामक हो जाते हैं क्योंकि उनके आसपास कोड, प्रक्रियाएं और टीम संरचनाएं बदलती हैं। दस्तावेज़ीकरण खुद जमा रहता है जबकि जो कुछ वह वर्णन करता है वह विकसित होता है।
Q: क्या Sugarbug डॉक्युमेंटेशन रॉट रोकने में मदद करता है? A: Sugarbug API के ज़रिए GitHub, Linear, Slack और Notion जैसे tools से जुड़ता है और आपके वर्कफ़्लो में वास्तव में क्या हुआ इसका नॉलेज ग्राफ़ बनाता है। मैन्युअली मेंटेन की गई विकी पेजों पर निर्भर रहने के बजाय, टीमें वास्तविक गतिविधि से वास्तविक संदर्भ प्राप्त कर सकती हैं, जो सटीक रहता है क्योंकि यह सीधे tools से लिया जाता है।
Q: इंजीनियरिंग दस्तावेज़ीकरण कितनी जल्दी पुराना हो जाता है? A: हमारे अनुभव और इंजीनियरिंग टीमों के साथ बातचीत से पता चलता है कि विकी पेज अक्सर बनाए जाने के पहले कुछ हफ्तों में ही वास्तविकता से अलग होने लगते हैं। छह महीनों में, कई पेज ऐसी प्रक्रियाओं, endpoints या स्वामित्व संरचनाओं का वर्णन करते हैं जो अपने दस्तावेज़ीकृत रूप में अब मौजूद नहीं हैं।
Q: इंजीनियरिंग docs को current रखने का सबसे अच्छा तरीका क्या है? A: जो approaches सबसे अच्छा काम करती हैं वे हैं code-adjacent documentation (READMEs और ADRs repo में), automated staleness alerts, और ऐसी living queries की ओर बढ़ना जो आपके actual tools से context pull करें – बजाय manually maintained pages पर निर्भर रहने के। Process checklists ("हर PR में docs अपडेट करो") लगातार fail होती हैं क्योंकि इनसेंटिव संरचना उन्हें support नहीं करती।