În acest articol, voi discuta secretul pentru a nu uita niciodată cum funcționează proiectul dvs., în trei pași.
Dacă ați scris vreodată pe jumătate un proiect software înainte de a lua câteva zile libere, acesta este articolul de care veți descoperi că aveți nevoie când redeschideți IDE-ul respectiv.
În echipele tehnologice pe care le conduc, facem un efort constant pentru a documenta toate lucrurile. Documentația trăiește alături de cod ca un jucător egal.
Acest lucru vă ajută să vă asigurați că nimeni nu trebuie să facă presupuneri cu privire la modul în care funcționează ceva sau nu convoca întâlniri lungi pentru a dobândi cunoștințe de lucru despre o caracteristică. O documentație bună ne economisește mult timp și probleme.
Acestea fiind spuse și contrar credinței populare, cea mai valoroasă documentație software nu este scrisă în primul rând pentru alte persoane. După cum am spus în acest tweet bine primit:
Secretul unei bune documentații este să o scrieți în timp ce scrieți codul. Ești primul tău public. Explicați-vă ce vă faceți. Viitor îți vei mulțumi!
– Victoria Drake 24 noiembrie 2020
Iată trei pași concreți pe care îi puteți face pentru a scrie o documentație bună înainte de a fi prea târziu.
1. Începeți cu note precise
Pe măsură ce elaborați idei în cod, asigurați-vă că nu uitați curând detalii importante, începând cu note precise. Deși veți dori să vă explicați lucrurile în formă lungă mai târziu, notele în formă scurtă vor fi suficiente pentru a captura detalii fără a întrerupe fluxul sesiunii de codare.
Păstrați un document deschis alături de codul dvs. și scrieți lucruri precum comenzi, decizii și surse pe care le utilizați. Aceasta poate include:
- Comenzile terminale pe care le-ați introdus
- De ce ați ales o anumită metodă în locul alteia
- Link-uri pe care le-ați vizitat pentru ajutor sau tusecopiaza si lipestetuse inspirație
- Ordinea în care ai făcut lucrurile
Nu vă faceți griji cu privire la propozițiile complete în acest moment. Asigurați-vă că capturați cu precizie contextul, fragmentele de cod relevante și adresele URL utile. De asemenea, poate fi util să activați orice opțiune de salvare automată disponibilă.
2. Explicați deciziile într-o formă lungă
Momentul ideal pentru a aborda acest pas este când faceți o pauză de la codare, dar înainte de a ieși complet la prânz pe orice lucru la care lucrați în acest moment.
Vrei să te asiguri că contextul, ideile și deciziile sunt în continuare proaspete în mintea ta când le explici.
Treceți peste notele de formă scurtă pe care le-ați luat și începeți să le extindeți în scrierea conversațională. Fii propria ta rață de cauciuc. Descrieți ceea ce faceți ca și când l-ați învăța pe altcineva. S-ar putea să abordați subiecte precum:
- Decizii ciudate: „În mod normal aș face-o așa, dar am ales să fac ceva diferit pentru că …”
- Provocări cu care ai întâmpinat și cum le-ai depășit
- Decizii arhitecturale care vă susțin obiectivele proiectului
Rămâneți la punctele principale. Scrierea în formă lungă nu înseamnă că vei fi plătit de cuvânt! Folosește doar propoziții complete și scrie ca și cum ai explica proiectul tău unui coleg. La urma urmei, îți explici viitorul.
3. Nu neglija cunoștințele prealabile
Acest pas se face cel mai bine după o pauză lungă de prânz sau chiar a doua zi (dar probabil nu două). Citiți din nou documentul dvs. și completați toate spațiile libere care devin evidente după ce ați pus o anumită distanță între dvs. și proiect.
Aveți grijă suplimentară să completați sau cel puțin să vă conectați la cunoștințe prealabile, mai ales dacă utilizați frecvent diferite limbi sau instrumente. Chiar și o acțiune la fel de mică precum lipirea într-un link către documentația API pe care ați folosit-o poate economisi ore de căutare viitoare.
Scrieți sau legați la README, pașii de instalare și problemele de asistență relevante. Pentru acțiuni efectuate frecvent pe linia de comandă, puteți utiliza un auto-documentare Makefile pentru a evita să trebuiască man sarcini comune de fiecare dată când reveniți la un proiect.
Este ușor să uitați detaliile de susținere după chiar o scurtă pauză de la proiectul dvs. Captează orice ai găsit util de data aceasta.
Documentează toate lucrurile!
Data viitoare când te surprinzi gândindu-te „Sunt sigur că îmi voi aminti această parte, nu este nevoie să o notez”, amintește-ți doar acest emoji: ????♀️
Proiectele software sunt alcătuite din mult mai mult decât doar codul lor. Pentru a vă configura cel mai bine sinele viitor pentru succes, documentați toate lucrurile! Fie că este vorba de un proces pe care l-ați stabilit, de infrastructură sub formă de cod sau de o viitoare idee de foaie de parcurs viitoare – scrieți-l! Viitor îți vei mulțumi pentru asta.
Dacă ți-ar plăcea această postare, mi-ar plăcea să știu. Alăturați-vă miilor de oameni care învață împreună cu mine victoria.dev! Vizitați și abonați-vă pentru mai multe despre construirea stivei de abilități de codare.
