Nga Alex Ponomarev
Kujtesa njerëzore i mbush boshllëqet, por jo gjithmonë saktë.
A jeni ndjerë ndonjëherë i sigurt për një fakt, vetëm për të zbuluar se e kishit gabim? Ndoshta ju kujtohet Njeriu i Monopoly-t me një monokël. Ose ndoshta mendoni se Arinjtë Berenstain shkruheshin Berenstein.
Asnjëra nuk është e vërtetë.
Ky është Efekti Mandela: kur grupe njerëzish e kujtojnë diçka në të njëjtën mënyrë, por është gabim. Nuk është thjesht harresë — është një kujtesë e rreme. Ndodh sepse truri ynë i mbush boshllëqet, përsërit gabimet, ose supozon detaje që nuk kanë qenë kurrë aty.
Në inxhinieri, ne e bëjmë këtë gjithashtu. Jo me monokla apo libra fëmijësh, por me:
-
Kod
-
Sisteme
-
Procese
-
Ose vendime
Ne mendojmë se e mbajmë mend se si funksionon diçka. Derisa nuk e mbajmë mend më.
Pse dokumentimi ka më shumë rëndësi sesa mendoni
Pyesni një zhvillues për një pjesë të vjetër kodi dhe ai do të thotë: “Po, e mbaj mend si funksionon kjo.”
Por kur t’i kthehet, ndoshta nuk do ta mbajë mend. Është njerëzore. Ne mund të mbajmë mend vetëm një sasi të caktuar, veçanërisht kur bombardohemi me sasi masive informacioni çdo ditë.
Nuk ka gjasa që një grup inxhinierësh të imagjinojnë një funksion që nuk ka ekzistuar kurrë. Por detajet zbehen dhe supozimet nuk janë gjithmonë të sakta.
Megjithatë, kjo nuk është thjesht një lapsus kujtese — bëhet një problem inxhinierik. Ekipet lëvizin përpara, projektet rriten dhe ajo që dikur ishte e qartë mund të kthehet lehtësisht në një lojë hamendjesh. Dokumentimi i kodit synon ta parandalojë këtë, por shpesh ai mund të jetë i paplotë, i vjetëruar ose të mungojë fare.
Si menaxher inxhinierie (EM), ju nuk e shkruani të gjithë kodin. Por ju jeni përgjegjës për të siguruar që ekipi juaj mund ta kuptojë, ta mirëmbajë dhe të ndërtojë mbi të. Kjo është arsyeja pse dokumentimi nuk është opsional — ose thjesht një “gjë e mirë për t’u pasur”. Është një domosdoshmëri strategjike dhe thellësisht njerëzore.
Dokumentimi është një manual mbijetese
Ndonjëherë, nuk do të keni ku të drejtoheni për të deshifruar një proces të paqartë, një variabël të vagullt ose një shërbim të ngatërruar.
Kur ndodh kjo, dokumentimi i mirë është litari juaj i shpëtimit:
-
Sqaron konfuzionin
-
Kursen kohë
-
Dhe i mban projektet në lëvizje
Pa të, ju mbeteni duke hamendësuar, duke gërmuar nëpër kod dhe duke u mbështetur te kujtesa. Gjë që vetëm humbet kohë dhe ngadalëson progresin.
Dokumentimi i mban ekipet në rrugën e duhur. Ai regjistron atë që ata ndërtuan dhe pse u morën vendimet. Ai harton sistemet komplekse dhe ruan zgjedhjet kyçe, duke e bërë punën e ardhshme më të lehtë dhe më efikase.
Heroi i heshtur i integrimit në punë (onboarding)
Imagjinoni të filloni një punë të re pa asnjë udhëzim. Ndoshta edhe ju ka ndodhur. Pa prezantime, pa shpjegime. Vetëm një grumbull kodi, pak kohë dhe një pritshmëri për ta kuptuar vetë. Kështu duket integrimi pa dokumentacion të duhur.
E vërteta është se inxhinierët e rinj nuk kanë nevojë të ndihen të humbur apo të mbingarkuar. Dokumentimi i mirë mund të jetë harta e tyre.
Në vend që të pyesin vazhdimisht shokët e skuadrës për ndihmë, të punësuarit e rinj mund të:
-
Shohin se si lidhen të gjitha pjesët e një sistemi
-
Kuptojnë arsyetimin pas vendimeve të vendosura
-
Dhe të përshtaten më shpejt pa u mbështetur në ndihmë të vazhdueshme
Por integrimi është vetëm një pjesë e enigmës. Dokumentimi i ndihmon të gjithë. Ai pengon zhdukjen e njohurive, i bën më të lehta dorëzimet e detyrave dhe përmirëson punën në grup.
Nuk ka të bëjë vetëm me lehtësinë. Ai i mban njohuritë me ekipin, jo të bllokuara në kokën e dikujt.
Ngjitësi social i inxhinierisë
Nëse jeni me fat, ekipi juaj ka atë personin që është “ngjitësi social”. Dikush që organizon ditët e tortës, interesohet për kolegët dhe e mban gjallë shpirtin e ekipit. Ata ndihmojnë në ndërtimin e marrëdhënieve të forta.
Dokumentimi është ekuivalenti teknik. Ashtu si ngjitësi social i lidh njerëzit, dokumentimi i mban bashkë njohuritë e një ekipi.
Dhe nuk është vetëm për një ekip. Dokumentimi lidh role të ndryshme në inxhinieri, duke përfshirë:
-
Frontend
-
Backend
-
Dizenjatorët
-
QA (Sigurimi i Cilësisë)
-
Dhe të tjerë
Çdo rol ndihmon në ndërtimin dhe mirëmbajtjen e sistemeve komplekse. Kur dokumentimi është i fortë, ai i mban ekipet bashkë. Kur mungon, gjërat shpërbëhen.
Ja pse:
1 — Dokumentimi është një burim qendror i së vërtetës
Ai i ndihmon të gjithë të kuptojnë se si lidhen pjesët e një sistemi. Në vend që të mbështeten te:
-
Mesazhe të shpërndara
-
Takime
-
Dhe fjalë goje
Ekipet mund të përdorin dokumentacion të qartë për proceset, API-të dhe vendimet arkitekturore.
Për shembull, një zhvillues frontend nuk duhet të hamendësojë se si funksionon një API. Ai duhet të ketë dokumentacion të qartë. E njëjta gjë vlen për një inxhinier QA, i cili ka nevojë për një udhëzues për sjelljen e pritur dhe rastet e testimit.
2 — Ai mbështet punën në distancë dhe atë asinkrone
Dokumentimi nuk është vetëm një shtyllë për ekipet në zyrë. Ata në distancë mbështeten në komunikimin me shkrim në vend të bisedave të shpejta ballë për ballë.
Pa dokumentacion, njohuritë janë të vështira ose kërkojnë kohë për t’u ndarë. Dhe nëse mungojnë detaje thelbësore, të punësuarit e rinj humbasin, ndodhin gabime dhe puna ngadalësohet.
Një sistem i dokumentuar mirë u lejon anëtarëve të ekipit të:
-
Kuptojnë proceset pa pritur për përgjigje
-
Punojnë në mënyrë asinkrone duke qëndruar në linjë me objektivat
-
Dhe të integrohen shpejt e të kontribuojnë më herët
3 — Ai zbaton qëndrueshmërinë
Çdo ekip inxhinierik ka flukse pune, praktika më të mira dhe standarde kodimi unike. Dokumentacioni i përbashkët ndihmon në zbatimin e këtyre standardeve në të gjithë kompaninë, duke siguruar, për shembull, që:
-
Rishikimet e kodit të ndjekin të njëjtat parime
-
Mjediset e zhvillimit të konfigurohen në mënyrë konsistente
-
Dhe lëshimet e veçorive të ndjekin një proces të strukturuar
Nëse nuk do të ekzistonte dokumentacioni i përbashkët, çdo ekip do t’i bënte gjërat ndryshe. Kjo do të rezultonte në mospërputhje, joefikasitet dhe keqkomunikim.
Dokumentimi nuk ka të bëjë vetëm me shkrimin e gjërave në mënyrë që të mos harrohet ekzistenca e tyre. Përkundrazi, ka të bëjë me:
-
Mbajtjen e ekipeve të lidhur
-
Reduktimin e fërkimit
-
Dhe sigurimin e bashkëpunimit të qetë midis roleve, vendndodhjeve dhe projekteve
Si po e riformëson dokumentimin Inteligjenca Artificiale (IA)
Le ta pranojmë, shkrimi i dokumentacionit mund të marrë kohë. Dhe kjo është një nga arsyet pse anashkalohet. Por mjetet e IA-së po e ndryshojnë këtë. IA mund të krijojë dhe përditësojë automatikisht dokumentet duke përdorur komentet dhe strukturën e kodit.
Mjete si Cursor skanojnë kodin dhe shkruajnë dokumente bazuar në emrat e funksioneve, parametrat dhe komentet. Kjo e mban dokumentacionin të përditësuar pa punë shtesë nga ekipet. Edhe kur kodi riorganizohet (refactored), dokumentacioni do të mbetet i saktë.
Dhe kjo është vetëm një pjesë e dokumentacionit. Formate të tjera si transkriptet e takimeve, bisedat në Slack dhe komentet në Jira, gjithashtu mund të konvertohen në dokumentacion.
Për shembull, imagjinoni se doni të shtoni një shërbim tjetër në aplikacionin tuaj. Me dokumentacionin dhe standardet e duhura, mjetet e IA-së mund ta shkruajnë shërbimin për ju. Në të njëjtën mënyrë, ato do të krijojnë dokumentacionin për shërbimin e ri.
Mjetet e IA-së gjithashtu e përmirësojnë dokumentacionin duke:
-
Mbushur boshllëqet e njohurive: Ato e mbajnë dokumentacionin të strukturuar, të saktë dhe të lehtë për t’u gjetur.
-
Ruajtur qëndrueshmërinë midis ekipeve: IA zakonisht ndjek një strukturë standarde. Kjo i lejon të gjithë të punojnë me dokumentacion të qartë e uniform.
-
Reduktuar gabimet dhe informacionin e vjetëruar: IA dallon detajet që mungojnë dhe mospërputhjet. Kjo i ndihmon ekipet ta mbajnë dokumentacionin e tyre të saktë.
Me përditësime të automatizuara, dokumentacioni mbetet aktual. Inxhinierët mund t’i besojnë asaj që lexojnë — dhe të kalojnë më pak kohë duke e vënë në dyshim. Mjetet e IA-së i çlirojnë inxhinierët nga përditësimet e përsëritura dhe manuale, duke i lejuar ata të përqendrohen në punë më kuptimplote.
Por sa është mjaftueshëm?
Kjo është një pyetje e vështirë, por ka disa udhëzime që mund të përdorni.
Shumë dokumentacion mund të jetë dërrmues. Dokumentet e gjata dhe komplekse mund t’i bëjnë njerëzit t’i kalojnë përmbajtjet shpejt e shpejt, duke anashkaluar detaje ose duke i kapërcyer ato plotësisht.
Pak dokumentacion mund të jetë po aq keq. Mungesa e udhëzimeve mund të çojë në supozime. Dhe supozimet mund të çojnë në gabime.
Qasja më e mirë është ta mbani dokumentacionin të lehtë, të qartë dhe të kërkueshëm. Në vend që të shkruani dokumente masive, përqendrohuni në atë që ekipet kanë vërtet nevojë.
Mundohuni ta mbani dokumentacionin tuaj:
-
Konciz: qëndroni te detajet më të rëndësishme
-
Të organizuar: përdorni tituj, pika dhe seksione të shkurtra
-
Të lehtë për t’u gjetur: skedarët Markdown, Google Docs ose wiki-t janë disa shembuj për ruajtjen e tij
Mbani mend, dokumentacioni i mirë u përgjigjet pyetjeve përpara se të bëhen. Ai duhet t’i udhëzojë inxhinierët pa i detyruar ata të gërmojnë nëpër faqe të pafundme. Njohuria e përbashkët duhet të jetë një mjet i dobishëm, jo një barrë.
Versioni i shkurtër: shkruaje, falënderoje veten më vonë
Kujtesa njerëzore nuk është e përsosur. Inxhinieria është komplekse. Dokumentimi i lidh pikat.
Pa të, ekipet mbështeten te kujtesa, mesazhet e shpërndara dhe takimet e pafundme. Kjo rezulton në konfuzion, vonesa dhe gabime. Dokumentimi i mirë shërben si një burim qendror i së vërtetës. Ai siguron që ekipet të qëndrojnë të lidhur dhe efikasë, dhe ndihmon me:
-
Integrimin: inxhinierët e rinj mund të kuptojnë shpejt sistemet pa u mbështetur te të tjerët
-
Bashkëpunimin: rolet e ndryshme (frontend, backend, QA, dizajnerët) punojnë së bashku pa probleme
-
Punën në distancë dhe të shpërndarë: njohuritë e shkruara u lejojnë ekipeve të punojnë në mënyrë asinkrone
-
Qëndrueshmërinë: dokumentacioni i përbashkët zbaton praktikat më të mira në të gjithë ekipet
Si menaxher inxhinierie, ju e jepni tonin. Nëse ekipi juaj ju sheh duke dokumentuar vendime dhe praktika më të mira, dhe duke e bërë njohurinë të dukshme — ata do t’ju ndjekin. Dhe nëse ju shohin duke e trajtuar dokumentacionin si një punë të rëndë? Edhe ata do ta bëjnë.
IA po e ndryshon dokumentimin. Ajo automatizon përditësimet, gjeneron dokumente nga kodi dhe i mban gjërat konsistente, duke hequr barrën prej tij.
Përdorni mjete të thjeshta për ta bërë më të lehtë. Tregoni vlerën e tij duke theksuar se si kursen kohë dhe parandalon gabime. Bëjeni zakon, jo detyrë.
