De ce este importantă scrierea documentelor de proiectare software

Felicitări, ești un dezvoltator independent competent. De la începuturile tale umile, poate lucrând ca tester, ai evoluat la un dezvoltator de echipă, apoi un dezvoltator senior, iar acum ai făcut un alt salt, cel mai mare dintre toate, la lucrul direct cu clienții.

Dar acolo unde celelalte tranziții au fost liniare, aceasta din urmă a fost exponențială. În timp ce în trecut primeai comenzile de marș de la un angajator care lucra cu clienți sau era el însuși în afacerea cu software, acum toate acele responsabilități care erau odată distribuite între testarea experților, managementul programelor etc., sunt toate ale tale. Și acum lucrați cu clienți care nu sunt în domeniul software; sunt într-o altă afacere care are nevoie de un software și nu au o viziune clară și precisă asupra a ceea ce își doresc de la tine. Aceasta este o provocare mult mai mare decât pare.

*Notă:* Aici, descriu clienți mai mici care doresc o armată unică de la dezvoltatorul lor. Nu este singurul traseu pe care îl poate parcurge un freelancer, iar aceștia nu sunt singurii clienți cu care lucrăm la Toptal, dar este ruta care îmi place cel mai mult. Desigur, dacă lucrați în echipă și nu pe cont propriu, unele dintre cele de mai jos nu se vor aplica. De exemplu, dacă utilizați metodologii Agile sau Scrum, probabil că veți dori să vă structurați jaloanele ușor diferit.

Ați auzit cu toții despre importanța supremă a comunicării. Nu puteți lucra dacă primiți câteva propoziții de descriere concisă prin Skype și spunând „Ne vedem peste trei luni când termin”. Trebuie să fii în comunicare cu clientul tău și, în fiecare etapă a muncii tale, asigură-te că ai idei congruente despre obiectiv, pentru că este rar într-adevăr ca un client să-ți trimită wireframes și o specificație funcțională detaliată. Veți avea o idee foarte generală despre ceea ce ar trebui să facă, să arate și să curgă software-ul. Dacă scrieți o aplicație bazată pe descrierea superficială cu care începeți de obicei, nu există aproape nicio șansă ca clientul dvs. să fie mulțumit de rezultat. În fiecare etapă, trebuie să vă repetați calea mai aproape de un acord.

După ce a lucrat ani de zile la companii care erau ele însele în domeniul software, în care toți cei din echipă erau din aceeași cultură, vorbeau aceeași limbă maternă, lucrau pe același hol, se întâlneau zilnic etc., a fost de remarcat faptul că Compania încă nu a obținut ceea ce își dorea în jumătate din timp. Nu vă înșelați: provocarea aici este enormă.

De ce contează documentele de proiectare software

Așadar, atunci când abordezi un nou proiect, înainte de a deschide chiar Xcode sau Visual Studio, trebuie să ai obiective de design clare și convenite . Și aceste obiective ar trebui stabilite într-un caiet de sarcini. Dacă clientul nu a scris unul, ar trebui să îl scrieți și să-l trimiteți pentru examinare înainte de a vă deschide IDE-ul. Și dacă întâlnești un client care spune: „Nu avem timp pentru documente de proiectare”, cu sinceritate, ar trebui să renunți la proiect pentru că ai probleme înainte. Specificația nu trebuie să fie deosebit de lungă; poate fi doar câteva pagini, dar cel puțin ar trebui să prezinte interfața cu utilizatorul, să includă wireframes (dacă există o componentă UI) și să stabilească etapele de finalizare.

Fără acest document, vei ajunge într-o buclă de echivoc aspre, clienții contestând ceea ce ți-au spus sau ce le-ai spus, trimițând cu furie decupaje din comunicări anterioare, interpretând și argumentând până când va veni momentul când clientul solicită că faceți modificări pentru a aduce aplicația în conformitate cu „ceea ce au cerut de fapt” și se așteaptă să faceți acele modificări fără plată.

Cu acest document de proiectare a software-ului, veți avea un răspuns la orice astfel de dispută: atunci când apar neînțelegeri, vă puteți referi la specificația cu care a fost de acord și la care clientul a aprobat-o, subliniind că ați îndeplinit-o la scrisoare. În loc de argumente supărate, veți face amendamente și clarificări documentului. În orice caz, clientul își va cere scuze pentru că a lăsat imprecizia să scape în primul rând.

Cu toții ne dorim clienți mulțumiți. Cu toții ne dorim o relație de lucru prietenoasă. Și cu toții ne dorim mândria unei lucrări bine făcute. Dar acestea nu pot fi atinse dacă există vreo vagitate cu privire la ceea ce este de fapt locul de muncă. Dacă clientul dvs. spune că un document de proiectare este prea multă muncă suplimentară, este treaba dvs. să-i explicați că adevărata muncă suplimentară va apărea atunci când trebuie făcute revizuiri din cauza unui fel de neînțelegere. Dacă clientul tot insistă să avansezi fără un astfel de document, ar trebui să accepți faptul că ai o relație imposibil de realizat și să pleci.

Ce ar trebui să specifice de fapt specificația de proiectare a software-ului?

Cel puțin, ar trebui să fie o descriere a aplicației dorite, criterii de finalizare și repere. Amintiți-vă că partajați ceea ce este cel mai bine descris ca cerințe și document funcțional, nu o specificație de implementare. Și cu excepția cazului în care o implementare specifică este un obiectiv declarat al clientului, modul în care o faci să funcționeze depinde de tine.

Interfața cu utilizatorul

Majoritatea proiectelor sunt aplicații, nu biblioteci sau cadre. Dar dacă se întâmplă să aveți unul dintre acestea ca livrabil, considerați-vă norocos, deoarece interfața cu utilizatorul este de departe cea mai problematică componentă a șablonului de document de proiectare și aproape întotdeauna duce la neînțelegeri. Mulți clienți vă vor trimite ilustrații perfecte create într-un editor grafic de un designer grafic care nu este programator. Dar problema este: aceste ilustrații nu spun nimic despre animații, stări de control (de exemplu, Este acest buton dezactivat? Dispare atunci când este inutilizabil?), sau chiar ce acțiuni să efectueze atunci când un buton este apăsat.

Înainte de a începe să scrieți codul din spatele acestor ilustrații, ar trebui să puteți răspunde la toate aceste întrebări. Mai exact, ar trebui să știți:

1. Comenzile sunt întotdeauna vizibile și/sau activate? În ce condiții se schimbă stările lor?
2. Arată ca un bitmap — este un buton?
3. Ce tranziții au loc între aceste stări și vederi? Și cum ar trebui să fie animate?

Dacă depinde de dvs. să generați interfața de utilizare pentru concurența clientului, faceți același lucru invers: utilizați un instrument wireframe și creați un set complet de layout-uri de ecran, inclusiv orice variante pe care vizualizările le arată în diferite stări ale aplicației. Aceasta poate fi o muncă exhaustivă și plictisitoare, dar nu veți regreta - vă poate scuti de la rescrierea unor cantități uriașe de cod și de la recrearea interfețelor din cauza unei neînțelegeri minore cu implicații majore. Dacă creați o aplicație duală (de exemplu, atât pentru iPhone, cât și pentru iPad), creați wireframes separate pentru ambele.

Dimensiunile ecranului sunt de asemenea importante. Există (în momentul scrierii) trei dimensiuni de ecrane iPhone. Wireframes separate pentru ecranele de 3,5” și 4” sunt probabil excesive, dar poate fi necesar să le faceți; în cele mai multe cazuri, puteți schimba pur și simplu proporțiile.

Dacă clientul dumneavoastră vă furnizează elemente grafice, asigurați-vă că acestea sunt dimensionate corect cu raporturile de aspect adecvate; transformarea oricărui bitmap care are text sau obiecte (cum ar fi cercuri) va introduce distorsiuni. Dacă nu se potrivesc, spuneți clientului să le recreeze cu dimensiunile potrivite. Nu presupuneți că puteți întinde un ecran de stropire de 3,5 inchi într-un ecran de stropire de 4 inchi și doar rulați cu el.

Funcționalitate

Întrebări cheie de adresat în documentul de proiectare a aplicației:

• Ce face aplicația și cât de repede o face?
• Care sunt posibilele condiții de defecțiune și cum sunt tratate?
• Ce operațiuni unice se fac la prima execuție (adică după instalare)?
• Dacă utilizatorul creează intrări de orice fel (de exemplu, marcaje), care sunt limitările?

Generalizează aceste idei și fii cât mai detaliat și minuțios posibil - pentru că erorile sau neînțelegerile aici vor însemna rescrierea codului.

Repere

Șablonul dvs. de specificații ar trebui să prezinte reperele clare. Dacă clientul dvs. scrie designul funcțional și al interfeței cu utilizatorul, ulterior ar trebui să conveniți asupra unui set de etape. Uneori, acestea sunt și praguri de facturare, dar cel puțin oferă o valoare clară pentru finalizare. Etapele pot fi în termeni de funcționalitate și/sau componente; pot fi chiar aplicații separate dacă concertul implică o suită de livrabile. Când este posibil, etapele de referință ar trebui să fie aproximativ egale ca durată.

Exemplu de specificații de proiectare software

Aici, voi prezenta structura exemplu a unui document de proiectare adecvat. Desigur, acest șablon ar trebui ajustat după cum este necesar. Pentru un alt exemplu, vezi specificația eșantionului lui Joel Spolsky, bazată pe acest articol. El abordează documentul ușor diferit, dar împărtășește un sentiment similar.

Declarație de obiective

Includeți un scurt paragraf care descrie proiectul și publicul vizat.

Descriere funcțională

Ce face aplicația? Ce stări ale aplicației (descrieri la nivel înalt ale scenariilor principale ale utilizatorilor) va întâlni utilizatorul?

De exemplu, descrierea dvs. funcțională ar putea arăta astfel:

• Prima alergare
• Crearea unui nou _____ (joc, căutare etc.)
• Operațiuni
• Comportamentul de fundal și prim-plan

Interfața cu utilizatorul

Includeți wireframes pentru fiecare pagină, cu descrieri detaliate ale:

• Fiecare control, inclusiv stări (activat/dezactivat/evidențiat) și operațiuni.
• Orientări și tranziții acceptate între ele.
• Funcționalitatea reprezentată.
• Eroare de manipulare.
• Dimensiuni și constrângeri.

Iată wireframes-urile legate de cea mai recentă aplicație a mea iOS, NotifEye:

Dacă sunteți interesat, am făcut aceste machete folosind instrumentul de wireframing de la Balsamiq.

De exemplu, descrierea interfeței dvs. de utilizare ar putea arăta astfel:

• Bară de navigare
  • Control de navigare din stânga: reveniți la pagina de pornire
  • Bara de titlu: ecranul curent sau numele operației
  • Buton nou: creați un lucru nou
• Vizualizare tabel
  • Secțiunea 0: Titlul secțiunii
  • Secțiunea 0 rânduri:
    • Control rând 0 (de exemplu, imagine)
    • Linia de text 0
    • Linia de text 2

Repere

După cum este descris mai sus, termenele limită pentru finalizare și rezultatele așteptate.

De exemplu, secțiunea de repere din șablonul documentului de proiectare ar putea arăta astfel:

1. Aplicație de fațadă care arată ecran și cu tranziții temporare și exemple de imagini/text
2. Protocol de comunicare: aplicația se conectează la rețea/server
3. Etapa funcțională 1: …
4. Aplicație Alpha (cu funcționalitate completă)
5. Stabilitate
6. Eliberare

Asigurați-vă că documentația software-ului rămâne relevantă

Nu vreau să insinuez că faza de proiectare s-a încheiat odată ce tu și clientul tău ați convenit asupra unui document de specificații. Vor exista întotdeauna detalii pe care niciunul dintre voi nu le-ați luat în considerare și, în timp ce vă uitați la rezultatele intermediare, atât dvs., cât și clientul, veți întâlni idei noi, modificări de design, defecte neașteptate de design și sugestii imposibil de realizat.

Designul va evolua, iar modificările ar trebui să fie surprinse în documentul dvs. În cei 25 de ani de experiență, nu am lucrat niciodată la un proiect în care acest lucru nu s-a întâmplat – și asta include propriile mele aplicații (adică, unde eram propriul meu client). Chiar și atunci, am creat un document de proiectare cu specificații detaliate și l-am ajustat după cum a fost necesar.

Mai presus de toate, păstrați legătura. Cel puțin de câteva ori pe săptămână, contactați-vă clientul, raportați progresul dvs., cereți lămuriri și asigurați-vă că împărtășiți viziuni identice. Ca un test de turnesol pentru comunicarea dvs., încercați să vă asigurați că dvs. și clientul dumneavoastră dați aceleași răspunsuri la aceste trei întrebări:

1. La ce tocmai lucra dezvoltatorul?
2. La ce lucrează dezvoltatorul în prezent?
3. La ce va lucra în continuare dezvoltatorul?