Kako napisati dobar dokument za dizajn softvera

Kao softverski inženjer provodim puno vremena čitajući i pišući projektne dokumente. Nakon što sam prošao stotine ovih dokumenata, iz prve sam ruke vidio snažnu korelaciju između dobrih dizajnerskih dokumenata i krajnjeg uspjeha projekta.

Ovaj je članak moj pokušaj da opišem što projektni dokument čini sjajnim .

Članak je podijeljen u 4 odjeljka:

  • Zašto pisati projektni dokument
  • Što uključiti u projektni dokument
  • Kako to napisati
  • Proces oko nje

Zašto pisati projektni dokument?

Dokument o dizajnu - poznat i kao tehnička specifikacija - opis je načina na koji planirate riješiti problem.

Već postoji mnogo radova o tome zašto je važno napisati dokument o dizajnu prije nego što zaronite u kodiranje. Dakle, sve što ću ovdje reći je:

Dokument o dizajnu najkorisniji je alat za osiguravanje ispravnog rada.

Glavni cilj dokumenta za dizajn je učiniti vas učinkovitijima prisiljavajući vas na razmišljanje o dizajnu i prikupljanje povratnih informacija od drugih. Ljudi često misle da je smisao projektnog dokumenta podučavati druge o nekom sustavu ili kasnije služiti kao dokumentacija. Iako to mogu biti korisne nuspojave, one same sebi nisu cilj.

Kao opće pravilo, ako radite na projektu koji bi mogao potrajati 1 mjesec ili više inženjera, trebali biste napisati projektni dokument. Ali nemojte se tu zaustaviti - puno manjih projekata moglo bi imati koristi i od mini dizajnerskog dokumenta.

Sjajno! Ako i dalje čitate, vjerujete u važnost dizajnerskih dokumenata. Međutim, različiti inženjerski timovi, pa čak i inženjeri iz istog tima, često vrlo različito pišu projektne dokumente. Pa razgovarajmo o sadržaju, stilu i procesu dobrog dokumenta o dizajnu.

Što uključiti u dokument o dizajnu?

Projektni dokument opisuje rješenje problema. Budući da je priroda svakog problema različita, prirodno biste željeli drugačije strukturirati svoj projektni dokument.

Za početak slijedi popis odjeljaka koje biste barem trebali razmotritiuključujući u sljedeći projektni dokument:

Naslov i ljudi

Naslov vašeg dizajnerskog dokumenta,autor (i) (trebao bi biti jednak popisu ljudi koji planiraju raditi na ovom projektu), recenzent (i)dokumenta (o tome ćemo više govoriti u odjeljku Proces u nastavku) i datumu zadnjeg ažuriranja ovog dokumenta.

Pregled

Sažetak na visokoj razini koji bi svaki inženjer u tvrtki trebao razumjeti i koristiti se za odlučivanje je li korisno za njih da pročitaju ostatak dokumenta. To bi trebalo biti najviše 3 odlomka.

Kontekst

Opis trenutnog problema, zašto je ovaj projekt neophodan, što ljudi moraju znati da bi procijenili ovaj projekt i kako se uklapa u tehničku strategiju, strategiju proizvoda ili tromjesečne ciljeve tima.

Ciljevi i neciljevi

Odjeljak Ciljevi trebao bi:

  • opišite utjecaj vašeg projekta na korisnika - gdje bi vaš korisnik mogao biti drugi inženjerski tim ili čak neki drugi tehnički sustav
  • navedite kako mjeriti uspjeh pomoću mjernih podataka - bonus bodova ako se možete povezati s nadzornom pločom koja prati te mjerne podatke

Neciljevi su jednako važni da opišu probleme koje nećete riješiti, pa su svi na istoj stranici.

Prekretnice

Popis mjerljivih kontrolnih točaka, tako da ga vaš PM i menadžer mogu proći i otprilike znati kada će se obaviti različiti dijelovi projekta. Savjetujem vam da rastavite projekt na glavne prekretnice usmjerene prema korisnicima ako je projekt dulji od 1 mjeseca.

Koristite datume kalendara kako biste uzeli u obzir nepovezana kašnjenja, odmore, sastanke i tako dalje. To bi trebalo izgledati otprilike ovako:

Start Date: June 7, 2018

Milestone 1 — New system MVP running in dark-mode: June 28, 2018

Milestone 2 - Retire old system: July 4th, 2018

End Date: Add feature X, Y, Z to new system: July 14th, 2018

Ovdje dodajte [Update]pododjeljak ako se ETA nekih od ovih prekretnica promijeni, tako da dionici mogu lako vidjeti najsuvremenije procjene.

Postojeće rješenje

Uz opis trenutne implementacije, trebali biste proći i kroz primjer protoka na visokoj razini kako biste ilustrirali kako korisnici komuniciraju s ovim sustavom i / ili kako podaci prolaze kroz njega.

korisnikapričaje sjajan način da se ovo uokviri. Imajte na umu da vaš sustav može imati različite tipove korisnika s različitim slučajevima korištenja.

Predloženo rješenje

Neki to nazivaju odjeljkom Tehnička arhitektura . Ponovno pokušajte prošetati kroz korisničku priču kako biste to konkretizirali. Slobodno uključite mnoge pododjeljke i dijagrame.

Prvo pružite veliku sliku, a zatim popunite punoodpojedinosti. Ciljajte na svijet u kojem možete ovo napisati, a zatim otići na odmor na neki pusti otok, a drugi inženjer iz tima to može jednostavno pročitati i implementirati rješenje kako ste opisali.

Alternativna rješenja

Što ste još uzeli u obzir prilikom donošenja gornjeg rješenja? Koje su prednosti i nedostaci alternativa? Jeste li razmišljali o kupnji rješenja treće strane - ili korištenja rješenja otvorenog koda - koje rješava ovaj problem umjesto da napravite vlastito?

Ispitivost, praćenje i upozoravanje

Volim uključiti ovaj odjeljak, jer se ljudi često prema tome odnose kao prema zadnjem razmišljanju ili sve skupa preskaču, a gotovo se uvijek vrati ugristi ih kasnije kad se stvari slome i nemaju pojma kako i zašto.

Utjecaj više timova

Kako će se ovo povećati u slučaju dežurstva i razvoja?

Koliko novca će to koštati?

Uzrokuje li to bilo kakvu regresiju latencije u sustavu?

Izlaže li neke sigurnosne ranjivosti?

Koje su neke negativne posljedice i nuspojave?

Kako bi tim za podršku mogao ovo priopćiti kupcima?

Otvorena pitanja

Bilo koja otvorena pitanja u koja niste sigurni, sporne odluke na kojima biste voljeli čitatelje razmotriti, predloženi budući rad itd. Jezični naziv za ovaj odjeljak je "poznate nepoznanice".

Detaljan opseg i vremenska crta

Ovaj će odjeljak uglavnom čitati samo inženjeri koji rade na ovom projektu, njihovi tehnološki voditelji i njihovi menadžeri. Stoga je ovaj odjeljak na kraju dokumenta.

U osnovi, ovo je analiza načina na koji i kada planirate izvršiti svaki dio projekta. Mnogo je toga što se precizno određuje, pa možete pročitati ovaj post da biste saznali više o opsegu.

Sklon sam također tretirati ovaj odjeljak projektnog dokumenta kao trajni tragač projektnih zadataka, pa ga ažuriram kad god se promijeni moja procjena opsega. Ali to je više osobna preferencija.

Kako to napisati

Sad kad smo razgovarali o tome što ulazi u dobar dokument o dizajnu, razgovarajmo o stilu pisanja. Obećavam da se ovo razlikuje od vašeg razreda engleskog u srednjoj školi.

Napišite što jednostavnije

Ne pokušavajte pisati kao akademski radovi koje ste pročitali. Napisani su kako bi impresionirali recenzente časopisa. Vaš je dokument napisan da opiše vaše rješenje i dobije povratne informacije od vaših suigrača. Jasnoću možete postići korištenjem:

  • Jednostavne riječi
  • Kratke rečenice
  • Označeni popisi i / ili numerirani popisi
  • Konkretni primjeri, poput "Korisnica Alice spaja svoj bankovni račun, a zatim ..."

Dodajte puno grafikona i dijagrama

Grafikoni često mogu biti korisni za usporedbu nekoliko potencijalnih opcija, a dijagrame je obično lakše raščlaniti nego tekst. Imao sam sreće s Google Drawingom za stvaranje dijagrama.

Savjet za profesionalce: ne zaboravite dodati vezu na verziju dijagrama koja se može uređivati ​​ispod snimke zaslona, ​​tako da je možete lako ažurirati kasnije kad se stvari neizbježno promijene.

Uključite brojeve

Razmjeri problema često određuju rješenje. Da biste pomogli recenzentima da steknu osjećaj za stanje u svijetu, uključite stvarne brojeve poput # DB redaka, # korisničkih pogrešaka, kašnjenja - i kako se one skaliraju s upotrebom. Sjećate se svojih Big-O notacija?

Pokušajte biti smiješni

Spec. Nije akademski rad. Također, ljudi vole čitati smiješne stvari, pa je ovo dobar način da čitatelja angažirate. Ipak, nemojte pretjerivati ​​do te mjere da oduzmete suštinsku ideju.

Ako i vi, poput mene, imate problema sa smiješnošću, Joel Spolsky ( očito poznat po svojim komičkim talentima ...) ima ovaj savjet:

Jedan od najlakših načina da budete smiješni jest biti određen kada to nije potrebno [... Primjer:] Umjesto da kažete „posebni interesi“, recite „ljevoruki farmeri avakada“.

Napravite Skeptički test

Prije nego što svoj dokument o dizajnu pošaljete drugima na pregled, napravite položnicu pretvarajući se da ste recenzent. Koja biste pitanja i sumnje mogli imati o ovom dizajnu? Zatim im se obratite preventivno.

Napravite test za odmor

Ako sada odete na dugi odmor bez pristupa Internetu, može li netko iz vašeg tima pročitati dokument i primijeniti ga kako ste namjeravali?

Glavni cilj dokumenta za dizajn nije dijeljenje znanja, ali ovo je dobar način da se procijeni jasnoća kako bi vam drugi zapravo mogli pružiti korisne povratne informacije.

Postupak

Ah da, zastrašujuća P-riječ . Dokumenti za dizajn pomažu vam da dobijete povratne informacije prije nego što potrošite hrpu vremena implementirajući pogrešno rješenje ili rješenje pogrešnog problema. Puno je umjetnosti za dobivanje dobrih povratnih informacija, ali to je za kasniji članak. Za sada, razgovarajmo konkretno o tome kako napisati projektni dokument i dobiti povratne informacije za njega.

Prije svega, svi koji rade na projektu trebali bi biti dio procesa dizajniranja. U redu je ako tehnološki voditelj na kraju donese puno odluka, ali svi bi trebali biti uključeni u raspravu i kupiti dizajn. Dakle, „vi“ u ovom članku zaista je množina „vi“ koja uključuje sve ljude na projektu.

Drugo, postupak dizajna ne znači da buljite u ideje o teoretiziranju ploče. Slobodno zaprljajte ruke i prototipirajte potencijalna rješenja. To nije isto kao i pisanje proizvodnog koda za projekt prije pisanja dokumenta o dizajnu. Nemoj to raditi. Ali apsolutno biste trebali slobodno napisati neki nesretni bacanje koda da biste potvrdili ideju. Da biste osigurali da pišete samo istraživački kôd, postavite pravilo da se niti jedan od ovog prototipa koda ne spoji u master .

Nakon toga, kad počnete imati neku ideju kako se baviti svojim projektom, učinite sljedeće:

  1. Zamolite iskusnog inženjera ili tehnološkog voditelja u svom timu da vam bude recenzent. U idealnom slučaju to bi bio netko tko je dobro poštovan i / ili upoznat s rubnim slučajevima problema. Podmitite ih bobom ako je potrebno.
  2. Uđite u konferencijsku sobu s bijelom pločom.
  3. Opišite problem s kojim se suočavate s ovim inženjerom (ovo je vrlo važan korak, nemojte ga preskočiti!).
  4. Zatim objasnite implementaciju na koju mislite i uvjerite ih da je to prava stvar za izgradnju.

Sve ovo prije nego što uopće započnete pisati svoj projektni dokument omogućuje vam povratne informacije što je prije moguće, prije nego što uložite više vremena i pridružite se bilo kojem određenom rješenju. Često, čak i ako implementacija ostane ista, vaš će recenzent moći ukazati na kutne slučajeve koje trebate pokriti, naznačiti potencijalna područja zabune i predvidjeti poteškoće s kojima biste se kasnije mogli susresti.

Zatim, nakon što napišete grubi nacrt vašeg dokumenta za dizajn, zatražite od istog recenzenta da ga ponovno pročita i stavite mu pečat dodavanjem imena kao recenzenta u odjeljku Naslov i ljudi dokumenta za dizajn. To stvara dodatni poticaj i odgovornost za recenzenta.

U toj bilješci razmislite o dodavanju specijaliziranih recenzenata (kao što su SRE i sigurnosni inženjeri) za određene aspekte dizajna.

Kad se vi i recenzent (i) odjavite, slobodno pošaljite projektni dokument svom timu radi dodatnih povratnih informacija i razmjene znanja. Predlažem da vremenski ograničite ovaj postupak prikupljanja povratnih informacija na otprilike 1 tjedan kako biste izbjegli dulja kašnjenja. Posvetite se rješavanju svih pitanja i komentara koje ljudi ostavljaju u tom tjednu. Ostavljanje komentara viseće = loša karma.

I na kraju, ako postoji mnogo prijepora između vas, vašeg recenzenta i ostalih inženjera koji čitaju dokument, toplo preporučujem objedinjavanje svih prijepornih točaka u odjeljku Rasprava vašeg dokumenta. Zatim zakažite sastanak s različitim stranama kako biste o tim nesuglasicama razgovarali osobno.

Kad god je nit rasprave duža od 5 komentara, prelazak na osobnu raspravu obično je daleko učinkovitiji. Imajte na umu da ste i dalje odgovorni za upućivanje konačnog poziva, čak i ako svi ne mogu postići konsenzus.

U nedavnom razgovoru sa Shreyem Bangom o tome, saznao sam da Quip ima sličan postupak, osim što osim što u vašem timu kao recenzent ima iskusnog inženjera ili tehnološkog voditelja, oni također predlažu da inženjer iz drugog tima pregleda dokument. Nisam ovo isprobao, ali sigurno vidim kako to pomaže u dobivanju povratnih informacija od ljudi s različitim perspektivama i poboljšanju opće čitljivosti dokumenta.

Nakon što napravite sve gore navedeno, vrijeme je da krenete u provedbu! Za dodatne bodove za brownie, tretirajte ovaj dokument o dizajnu kao živi dokument dok implementirate dizajn . Ažurirajte dokument svaki put kada naučite nešto što dovodi do promjene izvornog rješenja ili ažuriranja opsega. Zahvalit ćete mi kasnije kad ne budete morali iznova objašnjavati stvari svim svojim dionicima.

Konačno, na trenutak ćemo se dotaknuti meta: Kako ocjenjujemo uspjeh dizajnerskog dokumenta?

Moj kolega Kent Rakip ima dobar odgovor na ovo: Dokument o dizajnu uspješan je ako se izvrši pravi ROI posla. To znači da bi uspješan projektni dokument zapravo mogao dovesti do ovakvog ishoda:

  1. Provodite 5 dana pišući projektni dokument, što vas prisiljava na razmišljanje kroz različite dijelove tehničke arhitekture
  2. Dobijate povratne informacije od recenzenata koji Xsu najrizičniji dio predložene arhitekture
  3. Odlučili ste da ćete Xprvo provesti projekt s ciljem smanjenja rizika
  4. Tri dana kasnije shvatite da Xto ili nije moguće ili je daleko teže nego što ste prvotno namjeravali
  5. Odlučili ste prestati raditi na ovom projektu i umjesto toga prioritet dati drugim radovima

Na početku ovog članka rekli smo da je cilj dokumenta za dizajn osigurati da se obavi pravi posao. U gornjem primjeru, zahvaljujući ovom dizajnerskom dokumentu, umjesto da gubite potencijalne mjesece samo da biste kasnije prekinuli ovaj projekt, potrošili ste samo 8 dana. Čini mi se prilično uspješnim ishodom.

Molimo ostavite komentar ispod ako imate pitanja ili povratne informacije! Također bih volio čuti o tome kako drugačije dizajnirate dokumente u svom timu.

Dajući kredit tamo gdje je kredit potreban, naučio sam puno gore navedenog radeći zajedno s nekim nevjerojatnim inženjerima u Plaidu (zapošljavamo! Dođite s nama dizajnirati i izgraditi neke slatke tehničke sustave) i Quori.

Ako vam se sviđa ovaj post, slijedite me na Twitteru za još postova o inženjeringu, procesima i pozadinskim sustavima.