Kā uzrakstīt labu programmatūras projektēšanas dokumentu

Kā programmatūras inženieris es daudz laika pavadu, lasot un rakstot dizaina dokumentus. Pēc tam, kad esmu izgājis cauri simtiem šo dokumentu, es no pirmavotiem esmu redzējis ciešu korelāciju starp labiem dizaina dokumentiem un galīgajiem projekta panākumiem.

Šis raksts ir mans mēģinājums aprakstīt to, kas padara dizaina dokumentu izcilu .

Raksts ir sadalīts 4 sadaļās:

  • Kāpēc rakstīt dizaina dokumentu
  • Kas jāiekļauj dizaina dokumentā
  • to uzrakstīt
  • Procesā ap to

Kāpēc rakstīt dizaina dokumentu?

Dizaina dokuments - pazīstams arī kā tehniskā specifikācija - ir apraksts par to, kā jūs plānojat atrisināt problēmu.

Jau ir daudz rakstu par to, kāpēc ir svarīgi uzrakstīt dizaina dokumentu pirms ienirt kodēšanā. Tāpēc viss, ko es šeit teikšu, ir:

Dizaina dokuments ir visnoderīgākais rīks, lai pārliecinātos, ka tiek paveikts pareizs darbs.

Dizaina dokumenta galvenais mērķis ir padarīt jūs efektīvāku, liekot pārdomāt dizainu un apkopot atsauksmes no citiem. Cilvēki bieži domā, ka dizaina dokumenta mērķis ir iemācīt citiem par kādu sistēmu vai kalpot kā dokumentācija vēlāk. Lai gan tās var būt labvēlīgas blakusparādības, tās pašas par sevi nav mērķis.

Parasti, ja jūs strādājat pie projekta, kas varētu aizņemt 1 vai vairāk inženiera mēneša, jums vajadzētu uzrakstīt dizaina dokumentu. Bet neapstājieties pie tā - arī daudzi mazāki projekti varētu gūt labumu no mini dizaina dokumenta.

Lieliski! Ja jūs joprojām lasāt, jūs ticat dizaina dokumentu nozīmei. Tomēr dažādas inženieru komandas un pat vienas komandas inženieri projektēšanas dokumentus bieži raksta ļoti atšķirīgi. Tātad parunāsim par laba dizaina dokumenta saturu, stilu un procesu.

Kas jāiekļauj dizaina dokumentā?

Projektēšanas dokumentā aprakstīts problēmas risinājums. Tā kā katras problēmas būtība ir atšķirīga, jūs, protams, vēlaties strukturēt savu dizaina dokumentu atšķirīgi.

Lai sāktu, sekojošais ir sadaļu saraksts, kas jums vismaz jāņem vērāiekļaujot nākamajā dizaina dokumentā:

Tituls un cilvēki

Jūsu dizaina dokumenta nosaukumsautors (-i) (jābūt vienādam ar to cilvēku sarakstu, kuri plāno strādāt pie šī projekta), recenzents (-i)dokumenta (mēs par to vairāk runāsim sadaļā “Process”) un datumu, kurā šis dokuments pēdējo reizi tika atjaunināts.

Pārskats

Augsta līmeņa kopsavilkums, kas katram uzņēmuma inženierim jāsaprot un jāizmanto, lai izlemtu, vai viņiem ir noderīgi izlasīt pārējo dokumentu. Tam vajadzētu būt ne vairāk kā 3 rindkopām.

Konteksts

Raksturotās problēmas apraksts, kāpēc šis projekts ir nepieciešams, kas cilvēkiem jāzina, lai novērtētu šo projektu un kā tas iekļaujas tehniskajā stratēģijā, produkta stratēģijā vai komandas ceturkšņa mērķos.

Mērķi un citi mērķi

Sadaļā Mērķi:

  • aprakstiet sava lietotāja ietekmi uz lietotāju - kur jūsu lietotājs varētu būt cita inženieru komanda vai pat cita tehniskā sistēma
  • norādiet, kā novērtēt panākumus, izmantojot metriku - bonusa punkti, ja varat izveidot saiti uz informācijas paneli, kas izseko šos rādītājus

Non-mērķi ir vienlīdz svarīgi, lai aprakstītu, kas problēmas jums nebūs iespējams nosaka tā visi ir tajā pašā lapā.

Pagrieziena punkti

Mērāmu kontrolpunktu saraksts, lai jūsu premjerministrs un jūsu menedžera vadītājs varētu to noslaukt un aptuveni uzzināt, kad tiks veiktas dažādas projekta daļas. Es iesaku jūs sadalīt projektu galvenajos starpposmos, kas vērsti uz lietotājiem, ja projekts ir ilgāks par 1 mēnesi.

Izmantojiet kalendāra datumus, lai ņemtu vērā nesaistītus kavējumus, atvaļinājumus, sapulces utt. Tam vajadzētu izskatīties apmēram šādi:

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

Pievienojiet [Update]apakšsadaļu šeit, ja mainās dažu šo pagrieziena punktu ETA, lai ieinteresētās personas varētu viegli redzēt visjaunākos aprēķinus.

Esošais risinājums

Papildus pašreizējās ieviešanas aprakstam jums vajadzētu arī iziet cauri augsta līmeņa piemēra plūsmai, lai parādītu, kā lietotāji mijiedarbojas ar šo sistēmu un / vai kā dati caur to plūst.

lietotājustāstsir lielisks veids, kā to izveidot. Paturiet prātā, ka jūsu sistēmā var būt dažāda veida lietotāji ar dažādiem lietošanas gadījumiem.

Piedāvātais risinājums

Daži cilvēki to sauc par sadaļu Tehniskā arhitektūra . Atkal mēģiniet iepazīties ar lietotāja stāstu, lai to konkretizētu. Jūtieties brīvi iekļaut daudzas apakšnodaļas un diagrammas.

Vispirms sniedziet lielu attēlu, pēc tam aizpildiet partijasgadainformācija. Mērķējiet uz pasauli, kurā varat to uzrakstīt, pēc tam atvaļiniet kādā pamestā salā, un cits komandas inženieris to var vienkārši izlasīt un ieviest risinājumu, kā jūs aprakstījāt.

Alternatīvie risinājumi

Ko vēl jūs apsvērāt, piedāvājot iepriekš minēto risinājumu? Kādi ir alternatīvu plusi un mīnusi? Vai esat apsvēris iespēju iegādāties trešās puses risinājumu vai izmantot atvērtā koda risinājumu, kas atrisina šo problēmu, nevis veidot savu?

Pārbaudāmība, uzraudzība un brīdināšana

Man patīk iekļaut šo sadaļu, jo cilvēki to bieži uztver kā pēcpārdomu vai izlaiž to visu kopā, un tas gandrīz vienmēr atgriežas, lai viņus iekostu vēlāk, kad lietas salūzt un viņiem nav ne jausmas, kā un kāpēc.

Ietekme starp komandām

Kā tas palielināsies pēc izsaukuma un dev-ops sloga?

Cik tas maksās naudu?

Vai tas izraisa latentuma regresiju sistēmā?

Vai tas atklāj kādas drošības ievainojamības?

Kādas ir dažas negatīvas sekas un blakusparādības?

Kā atbalsta komanda to varētu paziņot klientiem?

Atklātie jautājumi

Visas atklātās problēmas, par kurām neesat pārliecināts, strīdīgi lēmumi, par kuriem vēlaties, lai lasītāji apsver, ieteiktie turpmākie darbi utt. Šīs sadaļas nosaukums “vaiga vaigā” ir “zināmie nezināmie”.

Detalizēta darbības joma un laika skala

Šo sadaļu lielākoties lasīs tikai inženieri, kas strādā pie šī projekta, viņu tehnoloģiju līderi un viņu vadītāji. Tāpēc šī sadaļa ir dokumenta beigās.

Būtībā tas ir sadalījums, kā un kad jūs plānojat izpildīt katru projekta daļu. Precīzā apjoma noteikšanā ir daudz, tāpēc varat izlasīt šo ziņu, lai uzzinātu vairāk par apjoma noteikšanu.

Es mēdzu arī izturēties pret šo projektēšanas dokumenta sadaļu kā notiekošu projekta uzdevumu izsekotāju, tāpēc es to atjauninu ikreiz, kad mainās mana darbības joma. Bet tas drīzāk ir personiska izvēle.

Kā to uzrakstīt

Tagad, kad mēs esam runājuši par to, kas nonāk labā dizaina dokumentā, parunāsim par rakstīšanas stilu. Es apsolu, ka tas atšķiras no jūsu vidusskolas angļu valodas klases.

Rakstiet pēc iespējas vienkāršāk

Nemēģiniet rakstīt tāpat kā lasītos akadēmiskos darbus. Tie ir rakstīti, lai atstātu iespaidu uz žurnālu recenzentiem. Jūsu dokuments ir uzrakstīts, lai aprakstītu jūsu risinājumu un saņemtu atsauksmes no komandas biedriem. Skaidrību var sasniegt, izmantojot:

  • Vienkārši vārdi
  • Īsi teikumi
  • Saraksti ar aizzīmēm un / vai numurēti saraksti
  • Konkrēti piemēri, piemēram, “Lietotāja Alise savieno savu bankas kontu, pēc tam…”

Pievienojiet daudz diagrammu un diagrammu

Diagrammas bieži var būt noderīgas, lai salīdzinātu vairākas iespējamās iespējas, un diagrammas parasti ir vieglāk parsēt nekā tekstu. Man ir paveicies ar Google Drawing, lai izveidotu diagrammas.

Pro padoms: neaizmirstiet pievienot saiti uz rediģējamo diagrammas versiju zem ekrānuzņēmuma, lai vēlāk to varētu viegli atjaunināt, kad lietas neizbēgami mainās.

Iekļaujiet skaitļus

Problēmas mērogs bieži nosaka risinājumu. Lai palīdzētu recenzentiem labāk izprast pasaules stāvokli, iekļaujiet reālus skaitļus, piemēram, # DB rindu, # lietotāju kļūdu, latentumu un to, kā šie mērogojas ar lietojumu. Vai atceraties savus Big-O apzīmējumus?

Centieties būt smieklīgi

Specifikācija nav akadēmisks darbs. Arī cilvēkiem patīk lasīt smieklīgas lietas, tāpēc tas ir labs veids, kā noturēt lasītāju. Tomēr nepārlieciet to līdz vietai, no kuras atņemat pamatideju.

Ja jums, tāpat kā man, ir problēmas būt smieklīgam, Džoelam Spoļskim ( acīmredzami pazīstamam ar saviem komēdijas talantiem ...) ir šāds padoms:

Viens no vienkāršākajiem veidiem, kā izklaidēties, ir būt specifiskam, ja to nepieprasa [… Piemērs:] Tā vietā, lai teiktu “īpašas intereses”, sakiet “kreiso roku avokado audzētāji”.

Veiciet skeptisko testu

Pirms nosūtāt dizaina dokumentu citiem pārskatīšanai, izlieciet to, uzdodoties par recenzentu. Kādi jautājumi un šaubas jums varētu būt par šo dizainu? Tad vērsieties pie viņiem preventīvi.

Veiciet atvaļinājuma testu

Ja tagad dodaties garās atvaļinājumā bez piekļuves internetam, vai kāds no jūsu komandas var izlasīt dokumentu un īstenot to, kā esat iecerējis?

Dizaina dokumenta galvenais mērķis nav zināšanu apmaiņa, taču tas ir labs veids, kā novērtēt skaidrību, lai citi faktiski varētu sniegt jums noderīgas atsauksmes.

Process

Ak jā, šausmīgais P vārds . Dizaina dokumenti palīdz iegūt atsauksmes, pirms jūs tērējat daudz laika, lai ieviestu nepareizu risinājumu vai nepareizas problēmas risinājumu. Lai iegūtu labu atgriezenisko saiti, ir daudz mākslas, bet tas ir paredzēts vēlākam rakstam. Pagaidām parunāsim tikai par to, kā uzrakstīt dizaina dokumentu un saņemt par to atsauksmes.

Pirmkārt, visiem, kas strādā pie projekta, vajadzētu būt projektēšanas procesa daļai. Tas ir labi, ja tehnoloģiju līderis galu galā izvirza daudzus lēmumus, taču ikvienam jābūt iesaistītam diskusijā un jāpiedalās dizainā. Tātad “jūs” šajā rakstā ir patiešām daudzskaitļa “jūs”, kas ietver visus projektā iesaistītos cilvēkus.

Otrkārt, projektēšanas process nenozīmē, ka jūs skatāties uz tāfeles teorētiskās idejas. Nekautrējieties sasmērēt rokas un prototipēt iespējamos risinājumus. Tas nav tas pats, kas sākt rakstīt projekta ražošanas kodu pirms dizaina dokumenta rakstīšanas. Nedari to. Bet jūs absolūti vajadzētu justies brīvi uzrakstīt kādu hacky reklamācija kodu, lai apstiprinātu ideja. Lai nodrošinātu, ka rakstāt tikai izpētes kodu, izveidojiet noteikumu, ka neviens no šī prototipa kodiem netiek apvienots ar galveno .

Pēc tam, kad jums ir kāda ideja par to, kā turpināt savu projektu, rīkojieties šādi:

  1. Palūdziet pieredzējušam inženierim vai tehnikas vadītājam savā komandā būt par savu recenzentu. Ideālā gadījumā tas būtu kāds, kurš ir cienīts un / vai pārzina problēmas galvenos gadījumus. Vajadzības gadījumā tos piekukuļojiet ar boba.
  2. Iet uz konferenču zāli ar tāfeli.
  3. Aprakstiet problēmu, ar kuru jūs vēršaties šim inženierim (tas ir ļoti svarīgs solis, neizlaižiet to!).
  4. Tad paskaidrojiet īstenošanu, kuru esat iecerējis, un pārlieciniet viņus, ka tā ir pareizā lieta.

To visu darot, pirms pat sākat rakstīt dizaina dokumentu, varat saņemt atsauksmes pēc iespējas ātrāk, pirms ieguldāt vairāk laika un esat piesaistīts jebkuram konkrētam risinājumam. Bieži, pat ja ieviešana paliek nemainīga, jūsu recenzents var norādīt uz stūra gadījumiem, kas jums jāaplūko, norādīt visas iespējamās neskaidrības un paredzēt grūtības, ar kurām vēlāk varētu rasties.

Pēc tam, kad esat uzrakstījis aptuvenu dizaina dokumenta melnrakstu, lieciet tam pašam recenzentam to vēlreiz izlasīt un nospiediet gumijas zīmogu, pievienojot viņu kā recenzentu dizaina dokumenta sadaļā Virsraksts un cilvēki . Tas rada papildu stimulu un pārskatatbildību recenzentam.

Šajā sakarā apsveriet iespēju pievienot specializētus recenzentus (piemēram, SRE un drošības inženierus) īpašiem dizaina aspektiem.

Kad esat parakstījis jūs un recenzents (-i), nosūtiet dizaina dokumentu savai komandai, lai saņemtu papildu atsauksmes un zināšanu apmaiņu. Es iesaku šo atgriezeniskās saites vākšanas procesu noteikt apmēram vienai nedēļai, lai izvairītos no ilgstošas ​​kavēšanās. Apņemieties pievērsties visiem jautājumiem un komentāriem, ko cilvēki atstāj šīs nedēļas laikā. Atstājot komentārus pakārt = slikta karma.

Visbeidzot, ja starp jums, recenzentu un citiem inženieriem, kas lasa dokumentu, ir daudz strīdu, es ļoti iesaku konsolidēt visus strīdus jautājumus sava dokumenta sadaļā Diskusija . Pēc tam izveidojiet tikšanos ar dažādām pusēm, lai klātienē runātu par šīm nesaskaņām.

Ikreiz, kad diskusijas pavediens ir garāks par 5 komentāriem, pāreja uz personisku diskusiju mēdz būt daudz efektīvāka. Paturiet prātā, ka jūs joprojām esat atbildīgs par pēdējā zvana veikšanu, pat ja visi nevar vienoties.

Nesen par to runājot ar Šriju Bangu, es uzzināju, ka Quip ir līdzīgs process, izņemot to, ka papildus tam, ka jūsu komandā kā recenzents ir pieredzējis inženieris vai tehnoloģiju vadītājs, viņi arī iesaka, lai citas komandas inženieris pārskata dokumentu. Es to neesmu izmēģinājis, bet noteikti redzu, ka tas palīdz saņemt atsauksmes no cilvēkiem ar atšķirīgu perspektīvu un uzlabo dokumenta vispārējo lasāmību.

Kad esat paveicis visu iepriekš minēto, ir laiks sākt darbu! Lai iegūtu papildu brownie punktus, rīkojoties ar dizainu , izturieties pret šo dizaina dokumentu kā dzīvu dokumentu . Atjauniniet dokumentu katru reizi, kad uzzināt kaut ko, kas liek mainīt sākotnējo risinājumu vai atjaunināt darbības jomu. Pateiksies man vēlāk, kad jums nevajadzēs atkal un atkal izskaidrot lietas visām ieinteresētajām pusēm.

Visbeidzot, pieņemsim īsti meta uz sekundi: Kā mēs novērtējam dizaina dokumenta panākumus?

Manam kolēģim Kentam Rakipam ir laba atbilde uz to: Dizaina dokuments ir veiksmīgs, ja tiek paveikta pareizā darba IA. Tas nozīmē, ka veiksmīgs dizaina dokuments faktiski var novest pie šāda rezultāta:

  1. Jūs pavadāt 5 dienas, rakstot dizaina dokumentu, tas liek pārdomāt dažādas tehniskās arhitektūras daļas
  2. Jūs saņemat atsauksmes no recenzentiem, kas Xir riskantākā piedāvātās arhitektūras daļa
  3. Jūs nolemjat vispirms īstenot, Xlai mazinātu projekta risku
  4. 3 dienas vēlāk jūs saprotat, ka Xvai nu nav iespējams, vai arī tas ir daudz grūtāk, nekā sākotnēji domājāt
  5. Jūs nolemjat pārtraukt darbu pie šī projekta un tā vietā piešķirt prioritāti citiem darbiem

Šī raksta sākumā mēs teicām, ka dizaina dokumenta mērķis ir pārliecināties, ka tiek veikts pareizs darbs. Iepriekš minētajā piemērā, pateicoties šim dizaina dokumentam, jūs esat tērējuši tikai mēnešus, lai vēlāk pārtrauktu šo projektu, bet jūs esat pavadījis tikai 8 dienas. Man tas šķiet diezgan veiksmīgs rezultāts.

Lūdzu, atstājiet komentāru zemāk, ja jums ir kādi jautājumi vai atsauksmes! Es arī labprāt dzirdētu par to, kā jūs savā komandā atšķirīgi veidojat dizaina dokumentus.

Piešķirot kredītus tur, kur pienākas kredīts, es uzzināju daudz iepriekš minētā, strādājot kopā ar dažiem neticamiem inženieriem Plaid (mēs pieņemam darbā! Nāciet, noformējiet un izveidojiet dažas saldas tehniskās sistēmas kopā ar mums) un Quora.

Ja jums patīk šī ziņa, sekojiet man Twitter, lai iegūtu vairāk ziņu par inženieriju, procesiem un aizmugures sistēmām.