Documentation Rot: Wiki ya Uhandisi Inakufa kwa Miezi 6
Wiki za uhandisi zinaoza haraka. Ratiba hii ya uchunguzi inaonyesha jinsi documentation rot inavyoanza na mifumo gani inayoizuia kweli.
By Ellis Keane · 2026-04-07
Kila timu ya uhandisi ina nafasi ya kazi ya Notion (au instansi ya Confluence, au wiki ya GitHub, au chombo chochote cha nyaraka kilichokuwa maarufu mwaka timu ilipoanzishwa) yenye ukurasa wenye kichwa kama "Service Architecture Overview" – uliohaririwa mara ya mwisho miezi kumi na moja iliyopita na mtu ambaye hafanyi kazi tena hapo. Ukurasa huo si nyaraka, ni kisukuku, na documentation rot iliyougeua kuwa kisukuku ilianza siku moja baada ya kuandikwa – takriban siku ile ile ambayo kila mtu alikubaliana kuwa "ni muhimu sana tuweke hii katika hali ya kisasa".
Ukurasa wa wiki unagandishwa wakati kila kitu kinachouzunguka kinaendelea kusonga. Hakuna anayeufuta, kwa sababu kufuta kunahisi kama uharibifu. Hakuna anayeusasisha, kwa sababu kusasisha kunahisi kama kazi ya mtu mwingine. Kwa hivyo unakaa tu hapo – ukionekana wenye mamlaka, polepole unakuwa hadithi ya kubuni. attribution: Ellis Keane
Tunaelekea kushughulikia documentation rot kama tatizo la nidhamu – kana kwamba wahandisi wanahitaji tu kujali zaidi kuhusu kuweka kurasa katika hali ya kisasa, kana kwamba kikwazo halisi ni motisha badala ya usanifu. Lakini baada ya kuona mtindo huu ukijirudia katika timu tunazozungumza nazo (na kwa uaminifu, ndani ya operesheni yetu ndogo – hatuna kinga dhidi ya yoyote ya haya), kushindwa daima ni sawa: nyaraka zinaishi mahali pamoja, mabadiliko ya msimbo yanafanyika mahali pengine, na hakuna mfumo unaoyaunganisha. Si suala la kujali. Ni suala la kutofautiana kwa msingi kati ya jinsi nyaraka zinavyofanya kazi na jinsi kazi ya uhandisi inavyotiririka kweli – na bado hatujapata suluhisho la mchakato peke yake kwa kutofautiana huko, ingawa tunaendelea kujaribu.
Ratiba ya Uchunguzi wa Ukurasa wa Wiki
Yafuatayo ni picha iliyounganishwa, iliyotolewa kutoka mazungumzo na timu za uhandisi na (kwa bahati mbaya) kutoka uzoefu wetu wenyewe, lakini mlolongo ni thabiti sana kati ya mashirika hivi kwamba maelezo mahususi karibu hayajalishi. Acha nionyeshe kinachotokea kweli kwa kipande cha nyaraka za ndani – kuanzia wakati kinachoundwa hadi wakati mtu anafanya uamuzi mbaya kwa sababu aliamini.
title: "Jinsi Ukurasa Mmoja wa Wiki Ulivyokuwa Hatari" Siku ya 1|ok|Mhandisi anaandika "Payment Service Architecture" baada ya refactoring kubwa. Sahihi, na maelezo kamili, ikijumuisha michoro ya mlolongo. Siku ya 14|ok|Watengenezaji wawili wanarejelea ukurasa wakati wa onboarding. Inawaokoa masaa. Ukurasa unaonekana kama mafanikio. Siku ya 31|amber|Mwanatimu anarekebisha mantiki ya kujaribu tena katika payment service. PR inaungana. Hakuna anayefikiria kuhusu ukurasa wa wiki. Siku ya 45|amber|Timu inahamia kutoka instansi ya Postgres inayoshirikiwa hadi ya kujitolea. Sehemu ya muunganisho wa hifadhidata kwenye ukurasa wa wiki sasa inaelezea miundombinu ambayo haipo tena. Siku ya 72|amber|Mhandisi mpya anasoma ukurasa na kusanidi mazingira ya ndani kulingana na usanidi wa hifadhidata ulioandikwa. Haifanyi kazi. Anatumia alasiri nzima kurekebisha hitilafu kabla ya mwenzake kusema: "ukurasa huo umepitwa na wakati." Siku ya 90|missed|Tukio linatokea saa 8 usiku. Mhandisi wa zamu anashauriana na ukurasa wa wiki kwa njia ya kuongeza kiwango cha huduma. Mmiliki aliyeorodheshwa aliondoka kampuni miezi miwili iliyopita. Dakika ishirini zinapotea kutafuta mtu sahihi. Siku ya 180|missed|Ukurasa umetazamwa mara kadhaa katika miezi sita. Umehaririwa mara sifuri tangu siku ya kwanza. Kila sehemu ina angalau taarifa moja isiyo sahihi. Hakuna anayejua ni sehemu zipi bado ni za kweli.
Ikiwa umefanya kazi katika timu yenye wahandisi zaidi ya watano, labda umeishi toleo fulani la ratiba hii. Ikiwa unatikisa kichwa chako sasa hivi ukifikiria "tuna mchakato kwa hilo", ninapendekeza kwa upole uangalie tarehe za mabadiliko ya mwisho kwenye wiki yako mwenyewe. Maelezo mahususi yanatofautiana (labda ni rejea ya API badala ya nyaraka za usanifu, labda ni Confluence badala ya Notion, labda tukio lilitokea saa 9 usiku badala ya saa 8) – lakini mkondo wa kuoza daima, kwa ukaidi, ni sawa.
Kwa Nini "Sasisha Tu Nyaraka" Kamwe Haifanyi Kazi
Jibu la kawaida zaidi kwa documentation rot ni mchakato: "Tunapaswa kusasisha nyaraka kama sehemu ya orodha ya ukaguzi wa PR." Inaonekana ya busara, na kwa uzoefu wetu inashindwa mara nyingi zaidi – kwa sababu zinazokuwa dhahiri unapofuatilia muundo wa motisha. Mhandisi anapojaribu kupata mapitio, kuunganisha na kusambaza mabadiliko kabla ya mwisho wa siku (na mwisho wa siku una tabia ya kufika haraka kuliko mtu yeyote alivyotarajia), ukurasa wa nyaraka unaorejelea kwa njia isiyo ya moja kwa moja sehemu aliyoibadilisha ni, kwa bora, ufahamu usio wazi nyuma ya akili, na mbaya zaidi, kitu ambacho kweli hajui kuwa kipo. Pipeline ya CI inageuka kijani, PR inaungana, na mtiririko wa kazi wa mtu yeyote haujumuishi hatua inayosema "sasa nenda utafute kila ukurasa wa wiki ambao kwa kimya ulidhani tabia ya zamani".
Na hii ndiyo sehemu ambayo hakuna anayetaka kusema kwa sauti: hata wakikumbuka ukurasa huo, mara nyingi hawajui hasa nini kinahitaji kubadilishwa. Uhusiano kati ya mabadiliko ya msimbo na athari zake za nyaraka si dhahiri kila wakati. Saini ya kazi iliyorekebisiwa inaweza kubatilisha kurasa tatu tofauti za wiki, ambazo hakuna inayotaja kazi hiyo kwa jina.
Documentation rot haisababishwi na uzembe. Inasababishwa na ukweli kwamba mabadiliko ya msimbo na mabadiliko ya nyaraka yanafanyika katika zana tofauti kabisa, wakati tofauti kabisa, na miundo ya motisha tofauti kabisa. Uhusiano kati yake unadumishwa kabisa katika kumbukumbu ya binadamu – na kumbukumbu ya binadamu si mfumo wa kuaminika wa kufuatilia utegemezi usio wa moja kwa moja.
Hatua Tatu za Documentation Rot
Nyaraka hazigeuki kutoka sahihi hadi hatari usiku mmoja – na ndivyo hasa kinachozifanya kuwa za hila sana. Zinapitia hatua tatu tofauti, kila moja ikiwa ngumu kugundua kuliko iliyopita, na hakuna wakati wowote mtu anapopokea arifa inayosema "hei, ukurasa huu sasa unawadanganya watu".
Hatua ya kwanza ni kutelekezana kwa nje – ambayo inaanza ndani ya wiki. Jina la kibadilishaji linabadilika, njia ya URL inasasishwa, jina la mwanatimu katika sehemu ya "Mmiliki" linakuwa lisilo sahihi baada ya mabadiliko ya shirika. Taarifa ya msingi bado ni sahihi kwa ujumla, na mtu anayesoma ukurasa atapata wazo sahihi la jumla hata kama maelezo mahususi yamebadilika. Hakuna kitu kinachoonekana kuwa kimeharibika bado (na karibu kamwe hakionekani wakati huu), kwa hivyo hakuna anayerekebisha chochote – kwa sababu kurekebisha ukurasa wa wiki uliotelekezana kwa nje ni sawa na kutumia uzi wa meno katika uhandisi: kila mtu anakubaliana kuwa ni muhimu, hakuna anayefanya leo.
Kisha inakuja kutengana kwa muundo – kawaida kati ya mwezi wa kwanza na wa tatu – ambapo usanifu wenyewe umebadilika zaidi ya kile ukurasa unaelezea. Labda huduma iligawanywa kuwa huduma mbili, au endpoint iliondolewa na kubadilishwa na moja yenye mkataba tofauti kabisa, au mtiririko wa uthibitishaji ulibadilishwa kabisa. Katika hatua hii, ukurasa unapotosha kikamilifu, lakini bado unaonekana wenye mamlaka (una michoro, una vichwa, uliandikwa wazi na mtu aliyejua alichokuwa akiongea) – kwa hivyo wasomaji wanauelekea kuamini kwa muda mrefu zaidi kuliko wanavyopaswa. Hiyo ndiyo sehemu hatari kweli.
Kufikia miezi ya tatu hadi sita, umefikia hadithi ya kubuni hatari. Ukurasa sasa unaelezea mfumo ambao haupo. Endpoint zilizoorodheshwa zinarudisha 404. Schema ya hifadhidata imehamishwa mara mbili. Njia ya kuongeza kiwango inaongoza kwa mtu ambaye kwa sasa anafanya kazi katika kampuni nyingine na labda amesahau kuwa huduma hiyo iliwahi kuwepo.
stat: "Mabadiliko sifuri" headline: "Katika miezi sita" source: "Mtindo uliogunduliwa katika wiki za uhandisi"
Uharibifu kutoka kwa documentation rot katika hatua hii si wa kinadharia. Wahandisi wanafanya maamuzi ya usambazaji, maamuzi ya kukabiliana na matukio, na maamuzi ya onboarding kulingana na nyaraka ambazo ni – kwa kusema wazi – hadithi za kubuni zenye muundo.
Kile Kinachopunguza Kasi ya Kuoza Kweli
Ikiwa orodha za ukaguzi wa mchakato hazifanyi kazi (na hazifanyi kazi, kwa sababu za muundo zilizoelezwa hapo juu), ni nini kinachofanya kazi? Jibu la uaminifu ni kwamba hakuna kitu kinachoondoa documentation rot kabisa, lakini timu fulani zinafanikiwa kupunguza kasi yake ya kutosha ili nusu ya maisha ya ukurasa wa wiki yaenee kutoka wiki hadi miezi – ambayo ni tofauti kati ya "mara kwa mara ya kupotosha" na "hatari kikamilifu". Timu tulizozungumza nazo ambazo zinafanya vizuri zaidi zinashiriki mitindo michache inayostahili kuchunguzwa.
Nyaraka zinazoishi karibu na msimbo. README katika repo, maoni ya ndani, rekodi za maamuzi ya usanifu (ADR) zilizowekwa pamoja na msimbo zinazouelezea. Hizi zina faida ya asili: msimbo unapobadilika, nyaraka ziko hapo, zikimtazama mhandisi katika diff sawa. Hakuna uhakikisho kuwa zitasasishwa (hakuna kitu kinachohakikishiwa), lakini ukaribu peke yake unafanya uwezekano kuwa mkubwa zaidi.
Kugundua kwa moja kwa moja upitaji. Timu fulani zinafanya script rahisi inayoweka alama kwenye ukurasa wowote wa wiki ambao haujahaririwa kwa siku 90. Ni mbichi, lakini inaleta tatizo juu kabla ya hatua ya 3 kufika. Utaratibu ni muhimu kidogo kuliko kanuni: shughulikia usahihi wa nyaraka kama kitu kinachoweza kupimwa, si tu kutumaini.
Nyaraka chache, fupi zaidi. Muhtasari wa usanifu wa maneno 3,000 utaoza haraka kuliko kurasa tatu zilizolenga za maneno 500 kuhusu vipengele mahususi. Eneo dogo la uso linamaanisha kila ukurasa una vitu vichache vinavyoweza kwenda vibaya, na mtu anayehusika na kuuweka katika hali ya kisasa anaweza kweli kukumbuka ukurasa mzima akilini.
Kinachopunguza kasi ya kuoza
- Nyaraka za karibu na msimbo – README na ADR katika repo, zinazosasishwa katika PR sawa
- Arifa za upitaji – alama za moja kwa moja kwa kurasa ambazo hazijaguswa kwa siku 90
- Kurasa ndogo, zilizolenga – eneo dogo la uso kwa kuoza kushikamana
Kisichosaidia
- Orodha za ukaguzi wa PR – "Sasisha nyaraka" kama kisanduku cha kuangalia kinachotiwa alama bila hatua
- Sprint za nyaraka – wiki moja ya masasisho yanayooza ndani ya mwezi
Tatizo la Kina Zaidi: Nyaraka ni Picha, Kazi ni Mkondo
Marekebisho yote hapo juu ni upunguzaji, na tunapaswa kuwa waaminifu kuhusu hilo. Tatizo la msingi ni kwamba nyaraka, kwa asili yake, ni picha ya wakati wa kitu kinachobadilika kila wakati – na hakuna kiasi cha tabaka za mchakato kinachobadilisha mvutano huo wa msingi. Unaandika jinsi mfumo unavyoonekana leo, kesho mfumo ni tofauti, nyaraka tayari zinaoza, na hakuna atakayegundua hadi mtu anapochomwa.
Timu zinazopambana kidogo zaidi na tatizo hili (na bado tunajaribu kuelewa "kidogo zaidi" kunaonekanaje – kwa sababu hakuna aliyetatua hili kweli) ni zile ambazo zimehamia kutoka nyaraka tuli hadi muktadha hai unaoulizika. Badala ya kuandika "payment service inamilikiwa na timu ya jukwaa", wana zana zinazoweza kujibu swali "ni nani amekuwa akifanya kazi kwenye payment service hivi karibuni?" kwa kuangalia commit halisi, PR na mazungumzo ya Slack ambapo maamuzi ya kweli yalifanywa.
Kwa usahihi, hiyo inamaanisha umiliki unaotolewa kutoka CODEOWNERS na waandishi wa commit wa hivi karibuni, historia ya usambazaji iliyovutwa kutoka CI, wajibuji wa matukio waliotafutwa kutoka kumbukumbu za pager, na muktadha wa maamuzi uliofuatiliwa kupitia masuala ya Linear yaliyounganishwa na mazungumzo ya Slack. Si wiki, na si usimamizi wa maarifa kwa maana ya jadi ya neno hilo. Ni faharasa hai inayobaki ya kisasa kwa sababu inatoa kutoka zana ambazo watu tayari wanatumia – badala ya kuwauliza kudumisha kitu tofauti ambacho (bila shaka, kwa utabiri) kitaoza.
Nyaraka za kuaminika zaidi ni aina ambayo hakuna mtu anayehitaji kuandika. Muktadha unapotolewa kutoka zana ambapo kazi kweli inafanyika (repo za msimbo, vifuatiliaji vya masuala, njia za mawasiliano), unaoza polepole zaidi – kwa sababu unaonyesha kinachotokea kweli badala ya kile mtu alikumbuka kuandika.
Unapohitaji Kweli Nyaraka za Jadi
Hakuna kitu hapo juu kinachomaanisha wiki hazina thamani. Kuna makundi mahususi ya nyaraka ambayo kweli yanafaidika kuandikwa na binadamu, kudumishwa kwa makusudi, na kuhifadhiwa kama nathari:
- Miongozo ya onboarding – inayoelezea "kwa nini" nyuma ya maamuzi ya usanifu, si tu "nini"
- Runbook – kwa kukabiliana na matukio, ambapo hadhira ni mhandisi aliyeshinikizwa saa 8 usiku anayehitaji orodha ya ukaguzi, si swali la grafu ya maarifa
- Nyaraka za utiifu – zinazohitajika na wakaguzi wanaotarajia vitu vilivyoundwa na vilivyopewa toleo
- Rejea za API za umma – zinazotumiwa na watengenezaji wa nje
Utofautishaji muhimu: nyaraka hizi zinaelezea mambo yanayobadilika polepole (thamani za kampuni, mahitaji ya utiifu, mikataba ya umma) au mambo ambapo muktadha wa masimulizi ni muhimu zaidi kuliko usahihi wa sasa (kwa nini tulichagua Postgres badala ya DynamoDB miaka mitatu iliyopita).
Kwa kila kitu kingine (nani anamiliki nini, usanifu wa sasa ni nini, uamuzi huo ulifanywa wapi), jibu halipaswi kuwa ukurasa wa wiki ambao mtu aliandika miezi sita iliyopita. Linapaswa kuwa swali kuhusu kilichotokea kweli.
Pokea akili ya ishara moja kwa moja kwenye sanduku lako la barua pepe.
Maswali Yanayoulizwa Mara kwa Mara
Q: Documentation rot katika timu za uhandisi ni nini? A: Documentation rot ni kupungua taratibu kwa usahihi wa nyaraka za ndani kadri muda unavyopita. Kurasa zilizokuwa sahihi zilipoandikwa zinakuwa za kupotosha kadri msimbo, michakato na miundo ya timu inavyobadilika. Nyaraka yenyewe inabaki imegandishwa wakati kila kitu inachoelezea kinaendelea kubadilika.
Q: Je, Sugarbug inasaidia kuzuia documentation rot? A: Sugarbug inaunganishwa na zana kama GitHub, Linear, Slack na Notion kupitia API, ikijenga grafu ya maarifa kuhusu kilichotokea kweli katika mtiririko wa kazi. Badala ya kutegemea kurasa za wiki zinazodumishwa kwa mikono, timu zinaweza kutoa muktadha halisi kutoka shughuli halisi – ambao unabaki sahihi kwa sababu unatoka moja kwa moja kwenye zana zenyewe.
Q: Nyaraka za uhandisi zinakuwa za zamani kwa haraka kiasi gani? A: Kwa uzoefu wetu na mazungumzo na timu za uhandisi, kurasa za wiki mara nyingi zinaanza kutofautiana na ukweli ndani ya wiki chache za kwanza baada ya kuundwa. Baada ya miezi sita, kurasa nyingi zinaeleza michakato, endpoint au miundo ya umiliki ambayo haipo tena katika hali iliyoandikwa.
Q: Njia bora ya kuweka nyaraka za uhandisi katika hali ya kisasa ni ipi? A: Mbinu bora zaidi ni nyaraka za karibu na msimbo (README na ADR katika repo), arifa za upitaji za moja kwa moja, na kuhamia kwenye maswali hai yanayotoa muktadha kutoka zana zako halisi badala ya kutegemea kurasa zinazodumishwa kwa mikono. Orodha za ukaguzi wa mchakato ("sasisha nyaraka katika kila PR") zinashindwa mara kwa mara kwa sababu muundo wa motisha hauziungi mkono.