Kuidas kirjutada hea tarkvara kujundamise dokument

Tarkvarainsenerina kulutan palju aega disainidokumentide lugemisele ja kirjutamisele. Pärast sadade nende dokumentide läbimist olen näinud omast käest tugevat seost heade disainidokumentide ja projekti lõpliku õnnestumise vahel.

See artikkel on minu katse kirjeldada, mis muudab disaindokumendi suurepäraseks .

Artikkel on jagatud 4 osaks:

  • Miks kirjutada kujundusdokument
  • Mida lisada kujundusdokumenti
  • Kuidas seda kirjutada
  • Selle ümber toimuv protsess

Miks kirjutada disaindokument?

Disainidokument - tuntud ka kui tehniline kirjeldus - kirjeldab probleemi lahendamist.

Juba praegu on palju kirjutisi selle kohta, miks on oluline enne kodeerimisse sukeldumist kujundusdokument kirjutada. Nii et kõik, mida ma siin ütlen, on:

Disainidokument on kõige kasulikum tööriist õige töö tegemiseks.

Disainidokumendi peamine eesmärk on muuta teid efektiivsemaks, sundides teid disaini läbi mõtlema ja teistelt tagasisidet koguma. Inimesed arvavad sageli, et disainidokumendi mõte on teistele mõne süsteemi õpetamine või hiljem dokumentatsioon. Kuigi need võivad olla kasulikud kõrvaltoimed on nad ei eesmärk ja ise.

Üldiselt rusikareeglina peaksite kirjutama disainidokumendi, kui töötate projektiga, mis võib võtta 1 või rohkem insenerikuud. Kuid sellega ei peatu - minidisainidokumendist võivad kasu olla ka paljud väiksemad projektid.

Suurepärane! Kui te alles loete, usute disainidokumentide olulisust. Kuid erinevad inseneride meeskonnad ja isegi sama meeskonna insenerid kirjutavad disainidokumente sageli väga erinevalt. Nii et räägime hea disainidokumendi sisust, stiilist ja protsessist.

Mida lisada disainidokumenti?

Disainidokument kirjeldab probleemi lahendust. Kuna iga probleemi olemus on erinev, peaksite loomulikult kujundusdokumendi teisiti üles ehitama.

Alustuseks on järgmine jaotiste loetelu, mida peaksite vähemalt kaalumasealhulgas oma järgmisesse disainidokumenti:

Pealkiri ja inimesed

Teie disainidokumendi pealkiriautor (id) (peaks olema sama, mis nimekiri inimestest, kes kavatsevad selle projektiga töötada), ülevaataja (d)(sellest räägime lähemalt allpool jaotises Protsess) ja selle dokumendi viimase värskendamise kuupäeva.

Ülevaade

Kõrgetasemeline kokkuvõte, millest iga ettevõtte insener peaks aru saama ja selle põhjal otsustama, kas neile on kasulik ülejäänud dokumenti lugeda. See peaks olema maksimaalselt 3 lõiku.

Kontekst

Käsitletud probleemi kirjeldus, miks see projekt on vajalik, mida inimesed peavad teadma selle projekti hindamiseks ja kuidas see sobib tehnilise strateegia, tootestrateegia või meeskonna kvartalieesmärkidega.

Eesmärgid ja mitte-eesmärgid

Jaotis Eesmärgid peaks:

  • kirjeldage oma projekti kasutajapõhist mõju - kus teie kasutajaks võib olla mõni teine ​​insenerimeeskond või isegi mõni muu tehniline süsteem
  • määrake, kuidas mõõdikute abil edu mõõta - boonuspunktid, kui saate linkida armatuurlauale, mis neid mõõdikuid jälgib

Mitte-eesmärgid on võrdselt olulised kirjeldamaks, milliseid probleeme te ei lahenda, nii et kõik oleksid samal lehel.

Verstapostid

Mõõdetavate kontrollpunktide loend, nii et teie peaminister ja teie mänedžeri juht saavad seda skimmitada ja teavad umbes, millal projekti erinevad osad tehakse. Kui projekt on üle ühe kuu pikk, soovitan teil jagada projekt peamisteks kasutajate jaoks suunatud verstapostideks.

Kasutage kalendrikuupäevi, et võtaksite arvesse mitteseotud viivitusi, puhkusi, koosolekuid jne. See peaks välja nägema umbes selline:

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

Lisage [Update]siia alajagu, kui mõnede nende verstapostide eeldatav eeldatav aeg muutub, nii et sidusrühmad näevad kõige ajakohasemaid hinnanguid hõlpsalt.

Olemasolev lahendus

Lisaks praeguse rakenduse kirjeldamisele peaksite läbima ka kõrgetasemelise näidevoo, et illustreerida, kuidas kasutajad selle süsteemiga suhtlevad ja / või kuidas andmeid selle kaudu liigub.

kasutajaluguon suurepärane viis selle raamistamiseks. Pidage meeles, et teie süsteemis võib olla erinevat tüüpi kasutajaid, kellel on erinevad kasutusjuhtumid.

Pakutud lahendus

Mõned inimesed nimetavad seda tehnilise arhitektuuri jaotiseks. Jällegi proovige selle konkretiseerida läbi kasutajaloo. Lisage julgelt palju alajaotisi ja skeeme.

Esmalt esitage suur pilt, seejärel täitke paljukohtaüksikasjad. Eesmärk on maailm, kus saate selle kirjutada, seejärel puhake mõnel mahajäetud saarel ja teine ​​meeskonna insener saab seda lihtsalt lugeda ja lahenduse rakendada, nagu te kirjeldasite.

Alternatiivsed lahendused

Mida veel arvestasite ülaltoodud lahenduse pakkumisel? Millised on alternatiivide plussid ja miinused? Kas olete kaalunud kolmanda osapoole lahenduse ostmist - või avatud lähtekoodiga lahenduse kasutamist -, mis lahendaks selle probleemi, mitte oma lahenduse loomine?

Testitavus, jälgimine ja hoiatamine

Mulle meeldib selle jaotise lisamine, sest inimesed käsitlevad seda sageli tagantjärele või jätavad selle kõik koos vahele ja see tuleb peaaegu alati tagasi, et neid hiljem hammustada, kui asjad purunevad ja neil pole aimugi, kuidas või miks.

Rühmadevaheline mõju

Kuidas see kõne- ja arendusteenuste koormus suureneb?

Kui palju see raha maksma läheb?

Kas see põhjustab süsteemile latentsusregressiooni?

Kas see paljastab turvanõrkusi?

Millised on mõned negatiivsed tagajärjed ja kõrvaltoimed?

Kuidas saaks tugitiim seda klientidele edastada?

Avatud küsimused

Kõik lahtised küsimused, milles te pole kindel, vaidlusalused otsused, millele soovite, et lugejad kaaluksid, soovitatud tulevased tööd ja nii edasi. Selle osa keelenurkne nimi on „teadaolevad tundmatud”.

Üksikasjalik ulatus ja ajaskaala

Seda jaotist loevad enamasti ainult selle projektiga tegelevad insenerid, nende tehnilised juhid ja nende juhid. Seega on see osa dokumendi lõpus.

Põhimõtteliselt on see jaotus selle kohta, kuidas ja millal kavatsete projekti iga osa ellu viia. Uurimise täpseks tegemiseks on palju, nii et saate selle postituse läbi lugeda, et saada lisateavet ulatuse määramise kohta.

Kaldun käsitlema ka seda disainidokumendi jaotist kui käimasolevat projektiülesannete jälgijat, nii et ajakohastan seda alati, kui mu ulatuse hinnang muutub. Kuid see on pigem isiklik eelistus.

Kuidas seda kirjutada

Nüüd, kui oleme rääkinud sellest, mis läheb heaks disainidokumendiks, räägime kirjutamisstiilist. Luban, et see erineb teie keskkooli inglise keele klassist.

Kirjutage võimalikult lihtsalt

Ärge proovige kirjutada nagu lugenud akadeemilised tööd. Need on kirjutatud ajakirjade arvustajatele muljet avaldama. Teie dokument on kirjutatud teie lahenduse kirjeldamiseks ja meeskonnakaaslastelt tagasiside saamiseks. Selguse saavutamiseks kasutage:

  • Lihtsad sõnad
  • Lühikesed laused
  • Täpp- ja / või nummerdatud loendid
  • Konkreetsed näited, näiteks „Kasutaja Alice ühendab oma pangakonto, siis…”

Lisage palju diagramme ja skeeme

Diagrammid võivad sageli olla kasulikud mitme võimaliku variandi võrdlemiseks ning skeeme on tavaliselt lihtsam sõeluda kui teksti. Mul on skeemide loomisel vedanud Google Drawinguga.

Pro näpunäide: ärge unustage ekraanipildi alla lisada skeemi redigeeritava versiooni linki, et saaksite seda hiljem hõlpsasti värskendada, kui asjad paratamatult muutuvad.

Kaasa numbrid

Probleemi ulatus määrab sageli lahenduse. Selleks, et ülevaatajad saaksid maailma olukorrast aimu, lisage reaalarvud, nagu # DB-ridade arv, kasutajavigade arv, latentsus ja kuidas need kasutamisega skaalal suurenevad. Kas mäletate oma Big-O tähistusi?

Püüa naljakas olla

Spetsifikatsioon ei ole akadeemiline töö. Samuti meeldib inimestele naljakaid asju lugeda, nii et see on hea viis hoida lugejat huvitatuna. Ära siiski liialda sellega, et võtad põhiidee ära.

Kui teil, nagu minulgi, on naljakas probleeme, on Joel Spolsky'l (kes on ilmselgelt tuntud oma koomiliste talentide poolest ...):

Üks lihtsamaid viise naljakaks teha on olla konkreetne, kui seda ei nõuta [… Näide:] Selle asemel, et öelda „erihuvid“, öelge „vasakukäelised avakadotalunikud“.

Tehke skeptiline test

Enne kui saadate oma disainidokumendi teistele ülevaatamiseks, andke sellele ülevaade teesklemiseks pass. Millised küsimused ja kahtlused võivad teil selle disaini kohta tekkida? Seejärel pöörduge nende poole ennetavalt.

Tehke puhkusetesti

Kui lähete nüüd pikale puhkusele ilma internetiühenduseta, kas keegi teie meeskonnast saab dokumenti lugeda ja selle oma kavatsuste kohaselt rakendada?

Disainidokumendi peamine eesmärk ei ole teadmiste jagamine, kuid see on hea viis selguse huvides hindamiseks, et teised saaksid teile tegelikult kasulikku tagasisidet anda.

Protsess

Ah jah, kardetud P-sõna . Disainidokumendid aitavad teil tagasisidet saada, enne kui raiskate hulga aega vale või vale probleemi lahenduse rakendamisele. Hea tagasiside saamiseks on palju kunsti, kuid see on hilisema artikli jaoks. Praegu räägime vaid konkreetselt sellest, kuidas disainidokumenti kirjutada ja selle kohta tagasisidet saada.

Kõigepealt peaksid kõik projekti kallal töötavad inimesed olema osa projekteerimisprotsessist. On okei, kui tehniline juht jõuab paljude otsuste langetamiseni, kuid kõik peaksid olema arutelusse kaasatud ja kavandisse sisse ostma. Nii et kogu see artikkel on teie sina, mis hõlmab kõiki projekti inimesi.

Teiseks, disainiprotsess ei tähenda, et te jõllitaksite ideede teoreetilist tahvlit. Määrige oma käed julgelt ja prototüüpige potentsiaalsed lahendused. See ei ole sama, mis alustada projekti tootekoodi kirjutamist enne disainidokumendi kirjutamist. Ära tee seda. Aga sa absoluutselt peab julgelt kirjutada mõned hacky throwaway koodi kinnitada idee. Ainult uurimiskoodi kirjutamise tagamiseks tehke reegel, et ühtegi prototüübikoodi ei ühendata masteriga .

Pärast seda, kui teil on idee oma projekti jätkamiseks, tehke järgmist:

  1. Küsige arvustajaks oma meeskonna kogenud inseneri või tehnikajuhti. Ideaalis oleks see keegi, kes on probleemi austatav ja / või tuttav probleemi äärmistega. Vajadusel anna neile altkäemaksu bobaga.
  2. Minge tahvliga konverentsisaali.
  3. Kirjeldage probleemi , millega selle inseneriga tegelete (see on väga oluline samm, ärge jätke seda vahele!).
  4. Seejärel selgitage, millist rakendust olete silmas pidanud, ja veenake neid, et see on õige asi, mida ehitada.

Kui teete seda kõike enne, kui isegi oma disainidokumenti kirjutama hakkate, saate võimalikult kiiresti tagasisidet, enne kui investeerite rohkem aega ja olete mõne konkreetse lahendusega seotud. Sageli, isegi kui juurutamine jääb samaks, suudab teie ülevaataja tuua välja nurgajuhtumid, mida peate kajastama, osutada võimalikele segaduse piirkondadele ja ennetada raskusi, mis teil hiljem võivad tekkida.

Seejärel, kui olete oma disainidokumendi ligikaudse mustandi kirjutanud, laske samal ülevaatajal see uuesti läbi lugeda ja pitserige see, lisades oma nime ülevaatajana disainidokumendi jaotises Pealkiri ja inimesed . See loob arvustajale täiendava stiimuli ja vastutuse.

Selles osas kaaluge disaini konkreetsete aspektide jaoks spetsiaalsete ülevaatajate (näiteks SRE-de ja turvainseneride) lisamist.

Kui olete koos ülevaataja (te) ga loginud, saatke disainidokument julgelt oma meeskonnale täiendava tagasiside ja teadmiste jagamiseks. Pikendatud viivituste vältimiseks soovitan selle tagasiside kogumise protsessi ajaliselt piirata umbes ühe nädalaga. Pühenduge vastama kõigile küsimustele ja kommentaaridele, mille inimesed selle nädala jooksul lahkuvad. Kommentaaride rippuma jätmine = halb karma.

Lõpuks, kui teie, retsensendi ja teiste dokumenti lugevate inseneride vahel on palju vaidlusi, soovitan tungivalt koondada kõik vaidlusküsimused oma dokumendi jaotisse Arutelu . Seejärel korraldage kohtumine erinevate osapooltega, et nendest erimeelsustest isiklikult rääkida.

Kui arutelulõng on pikem kui 5 kommentaari, kipub isikliku arutelu juurde liikumine olema palju tõhusam. Pidage meeles, et olete ikkagi vastutav viimase kõne tegemise eest, isegi kui kõik ei jõua konsensusele.

Hiljuti sel teemal Shrey Bangaga rääkides sain teada, et Quipil on sarnane protsess, välja arvatud see, et lisaks sellele, et teie meeskonnas on kogenud insener või tehniline juht retsensendina, soovitavad nad ka mõne teise meeskonna inseneril dokumenti üle vaadata. Ma pole seda proovinud, kuid kindlasti näen, et see aitab saada tagasisidet erineva perspektiiviga inimestelt ja parandada dokumendi üldist loetavust.

Kui olete kõik ülaltoodud teinud, on aeg juurutamiseks jätkata! Täiendavate brownie-punktide saamiseks käsitlege seda disainidokumenti elava dokumendina, kui disaini rakendate . Värskendage dokumenti iga kord, kui õpite midagi, mis viib esialgse lahenduse muudatuste tegemiseni või ulatuse värskendamiseni. Tänate mind hiljem, kui te ei pea kõigile oma sidusrühmadele asju uuesti ja uuesti selgitama.

Lõpuks olgem sekundiks tõesti meta: kuidas me hindame disainidokumendi edu?

Minu töökaaslasel Kent Rakipil on sellele hea vastus: disainidokument on edukas, kui on tehtud õige investeeringutasuvus. See tähendab, et edukas disainidokument võib tegelikult viia sellise tulemuseni:

  1. Te kulutate 5 päeva disainidokumendi kirjutamisele, see sunnib teid tehnilise arhitektuuri erinevaid osi läbi mõtlema
  2. Saate retsensentidelt tagasisidet, mis Xon kavandatud arhitektuuri kõige riskantsem osa
  3. Otsustate Xprojektiga riskide kaotamiseks kõigepealt rakendada
  4. 3 päeva hiljem saate aru, et see Xpole kas võimalik või palju raskem, kui algselt kavatsesite
  5. Otsustate selle projektiga töötamise lõpetada ja eelistate selle asemel muud tööd

Selle artikli alguses ütlesime, et disainidokumendi eesmärk on tagada õige töö tegemine. Ülaltoodud näites olete selle disainidokumendi tõttu kulutanud ainult 8 päeva, selle asemel, et raisata kuid vaid selle projekti hilisemaks katkestamiseks. Mulle tundub see üsna õnnestunud tulemus.

Kui teil on küsimusi või tagasisidet, jätke kommentaar allpool! Mulle meeldiks ka kuulda, kuidas te oma meeskonnas dokumente kujundate erinevalt.

Krediidi andmisel seal, kus krediit peaks maksma, õppisin palju ülaltoodut, töötades koos mõne imelise inseneriga Plaidis (võtame tööle! Tule meiega projekteerima ja ehitama mõnusaid tehnilisi süsteeme) ja Quoras.

Kui teile see postitus meeldib, jälgige mind Twitteris, et saada rohkem postitusi inseneri-, protsesside- ja taustsüsteemide kohta.