Kuidas kirjutada hea tarkvara kujundamise dok

Foto Estée Janssens saidil Unsplash

Tarkvarainsenerina veedan palju aega disainidokumentide lugemisel ja kirjutamisel. Pärast sadade nende dokumentide läbimist olen ma näinud tugevat seost heade disainilahenduste ja projekti lõpliku edu vahel.

See artikkel on minu katse kirjeldada, mis teeb disainidokumendi suurepäraseks.

Artikkel on jagatud neljaks osaks:

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

Miks kirjutada disainidokument?

Kujundusdokument - tuntud ka kui tehniline kirjeldus - kirjeldab, kuidas kavatsete probleemi lahendada.

Juba praegu on palju kirjutisi selle kohta, miks on oluline enne kodeerimisse sukeldumist kirjutada disainidokument. Nii et ma ütlen siin ainult järgmist:

Kujundusdokument on kõige kasulikum tööriist, et veenduda, kas õige töö saab tehtud.

Kujundusdokumendi peamine eesmärk on muuta teid efektiivsemaks, sundides teid disainilahenduse läbi mõtlema ja teistelt tagasisidet koguma. Inimesed arvavad sageli, et disainidokumendi mõte on õpetada teistele mõnda süsteemi või kasutada seda hiljem dokumentatsioonina. Kuigi need võivad olla kasulikud kõrvalmõjud, pole need iseenesest eesmärk.

Üldine rusikareegel, et kui töötate projekti kallal, mis võtab aega vähemalt üks insenerikuu või rohkem, peaksite kirjutama kujundusdokumendi. Kuid ärge lõpetage sellega - minidisainidokumendist võiks kasu olla ka paljudele väiksematele projektidele.

Tore! Kui loete endiselt, siis usute disainilahenduste olulisusse. Erinevad insenerimeeskonnad ja isegi sama meeskonna insenerid kirjutavad disainidokumente sageli väga erinevalt. Räägime siis hea kujundusdokumendi sisust, stiilist ja protsessist.

Foto autor Todd Quackenbush saidil Unsplash

Mida lisada kujundusdokumenti?

Kujundusdokument kirjeldab probleemi lahendust. Kuna iga probleemi olemus on erinev, soovite loomulikult oma kujundusdokumendi erinevalt struktureerida.

Alustuseks on allpool loend sektsioonidest, mida peaksite vähemalt kaaluma oma järgmisesse kujundusdokumenti lisama:

Pealkiri ja inimesed

Teie kujundusdokumendi pealkiri, autor (id) (peaks olema sama, kes selle projekti kallal töötavaid inimesi), dokumendi retsensend (id) (räägime sellest lähemalt peatükis Protsess) allpool) ja dokumendi viimase värskendamise kuupäeva.

Ülevaade

Kõrgetasemeline kokkuvõte, mida kõik ettevõtte insenerid peaksid mõistma ja kasutama, et otsustada, kas ülejäänud dokumentide lugemine on neile kasulik. See peaks olema maksimaalselt 3 lõiku

Kontekst

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

Eesmärgid ja mitte-eesmärgid

Jaotis Eesmärgid peaks:

  • kirjeldage oma projekti kasutajapõhist mõju - kus teie kasutaja võib olla mõni teine ​​insenerimeeskond või isegi mõni muu tehniline süsteem
  • täpsustage, kuidas mõõta mõõdikute abil edukust - boonuspunktid, kui saate linki neid mõõdikuid jälgivale armatuurlauale

Mitte-eesmärgid on võrdselt olulised ka nende probleemide kirjeldamisel, mida te ei lahenda, nii et kõik on samal lehel.

Verstapostid

Mõõdetavate kontrollpunktide loend, nii et teie juhataja ja teie mänedžer saavad seda skimeerida ja teavad umbkaudu, millal projekti erinevad osad tehakse. Soovitan teil jaotada projekt peamisteks kasutaja poole suunatud verstapostideks, kui projekt on üle ühe kuu pikk.

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

Alguskuupäev: 7. juuni 2018
1. verstapost - pimedas režiimis töötav uus süsteemi MVP: 28. juuni 2018
2. verstapost - vana süsteemi tagasiandmine: 4. juuli 2018
Lõppkuupäev: lisage funktsioon X, Y, Z uude süsteemi: 14. juuli 2018

Lisage siia alajaotus [Uuendamine], kui mõne nende verstapostini jõudmise ETA muutub, et sidusrühmad saaksid hõlpsasti näha kõige ajakohasemaid hinnanguid.

Olemasolev lahendus

Lisaks praeguse rakenduse kirjeldusele peaksite läbi käima ka kõrgetasemelise näitevoo, et illustreerida, kuidas kasutajad selle süsteemiga suhtlevad ja / või kuidas andmed läbi selle voolavad.

Kasutaja lugu on suurepärane viis selle kujundamiseks. Pidage meeles, et teie süsteemis võivad olla erinevat tüüpi kasutajad, kellel on erinevad kasutusjuhud.

Pakutud lahendus

Mõni inimene nimetab seda tehnilise arhitektuuri sektsiooniks. Proovige selle konkretiseerimiseks uuesti läbi käia kasutaja lugu. Lisage julgelt palju alajaotisi ja diagramme.

Esitage esmalt suur pilt, seejärel täitke palju üksikasju. Eesmärk on maailm, kus saate seda kirjutada, seejärel võtta puhkust mõnel mahajäetud saarel ja teine ​​meeskonna insener saab seda lihtsalt lugeda ja rakendada lahendust, nagu te kirjeldasite.

Alternatiivsed lahendused

Mida veel kaalusite ülaltoodud lahenduse pakkumisel? Millised on alternatiivide plussid ja miinused? Kas olete mõelnud kolmanda osapoole lahenduse ostmisele või avatud lähtekoodiga lahenduse ostmisele, mis lahendab selle probleemi, mitte teie enda?

Testatavus, seire ja hoiatused

Mulle meeldib selle jaotise lisamine, kuna inimesed käsitlevad seda sageli järelemõtlemisena või jätavad selle kõik vahele ja peaaegu alati tuleb neid hiljem hammustada, kui asjad lagunevad ja neil pole aimugi, kuidas või miks.

Meeskondadeülene mõju

Kuidas suureneb kõne- ja arendusoperatsioonide koormus?
Kui palju see maksab?
Kas see põhjustab süsteemile latentsuse regressiooni?
Kas see paljastab turvaauke?
Millised on mõned negatiivsed tagajärjed ja kõrvaltoimed?
Kuidas saaks tugimeeskond seda klientidega edastada?

Avatud küsimused

Kõik avatud teemad, milles te pole kindel, vaidlusalused otsused, mida soovite lugejatel kaaluda, soovituslikud tulevased tööd ja nii edasi. Selle lõigu keeleline-põskenimi on „tuntud tundmatud”.

Üksikasjalik ulatus ja ajakava

Seda jaotist loevad enamasti ainult selle projekti kallal töötavad insenerid, nende tehnilised juhtnöörid ja 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. Ulatuslikku ulatust läheb palju, nii et saate selle postituse lugeda, et saada lisateavet ulatuse määramise kohta.

Samuti kipun seda kujundusdokumendi jaotist käsitlema pideva projektiülesande jälgijana, seega värskendan seda iga kord, kui minu ulatuse hinnang muutub. Kuid see on rohkem isiklik eelistus.

Foto autor Rawpixel saidil Unsplash

Kuidas seda kirjutada

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

Kirjutage võimalikult lihtsalt

Ärge proovige kirjutada nagu akadeemilised tööd, mida olete lugenud. Need on kirjutatud ajakirjanike arvustuste avaldamiseks mulje avaldamiseks. Teie dokument on kirjutatud teie lahenduse kirjeldamiseks ja meeskonnakaaslastelt tagasiside saamiseks. Selguse saavutamiseks võite kasutada järgmist:

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

Lisage palju diagramme ja diagramme

Diagrammidest võib sageli olla kasu mitme võimaliku valiku võrdlemiseks ning diagramme on üldiselt lihtsam sõeluda kui teksti. Google'i joonistamisel on mulle diagrammide loomisel palju õnne olnud.

Pro-näpunäide: ärge unustage lisada lingi ekraanipildi alla skeemi redigeeritavale versioonile, nii et saate seda hiljem hõlpsalt värskendada, kui asjad paratamatult muutuvad.

Kaasa numbrid

Probleemi ulatus määrab sageli lahenduse. Lisage ülevaatajatele maailma olukorrast arusaam, lisage reaalarvud, näiteks DB ridade arv, # kasutajate vigade arv, latentsus - ja kuidas need skaleeruvad koos kasutamisega. Kas mäletate oma Big-O märkusi?

Püüdke naljakas olla

Spetsifikatsioon ei ole akadeemiline töö. Ka inimestele meeldib naljakaid asju lugeda, nii et see on hea viis lugeja kaasamiseks. Ärge sellega siiski üle pingutage, kui peate ideest eemale viia.

Kui teil, nagu minul, on raskusi naljaga, on Joel Spolsky (ilmselt tuntud oma koomiliste annete ...) järgi see näpunäide:

Üks lihtsamaid viise nalja saamiseks on olla konkreetne, kui seda pole vaja [… Näide:] „Eriliste huvide” asemel öelda „vasakukäelised lavakadutootjad”.

Tehke skeptikatse

Enne kui saadate oma kujundusdokumendi teistele ülevaatamiseks, proovige seda teeseldades, et olete retsensendiks. Millised küsimused ja kahtlused võivad teil selle kujunduse osas tekkida? Seejärel pöörduge ennetavalt nende poole.

Tehke puhkuseproov

Kui lähete nüüd pikale puhkusele, millel pole Interneti-ühendust, siis kas keegi teie meeskonnast saab dokumendi läbi lugeda ja selle kavandatud viisil rakendada?

Kujundusdokumendi peamine eesmärk pole teadmiste jagamine, kuid see on hea viis selguse hindamiseks, et teised saaksid teile tegelikult kasulikku tagasisidet anda.

Foto autor SpaceX saidil Unsplash

Protsess

Ah jah, kardetud P-sõna. Kujundusdokumendid aitavad teil tagasisidet saada, enne kui kulutate hulga aega vale lahenduse või valele probleemile lahenduse rakendamiseks. Hea tagasiside saamiseks on palju kunsti, kuid see on mõeldud hilisema artikli jaoks. Nüüd räägime lihtsalt konkreetselt sellest, kuidas kirjutada disainilahenduse dokument ja saada selle kohta tagasisidet.

Esiteks peaksid kõik, kes projekti kallal töötavad, olema osa projekteerimisprotsessist. On õige, kui tehnika juhtimine viib paljude otsuste langetamiseni, kuid kõik peaksid olema arutellu kaasatud ja disaini sisse ostma. Nii et "sina" kogu selle artikli kohta on tõesti mitmuse "sina", mis hõlmab kõiki projekti inimesi.

Teiseks, disainiprotsess ei tähenda, et te vahtiksite tahvlile teoreetilisi ideid. Võite oma käed räpaseks ja potentsiaalsete lahenduste prototüübiks teha. See ei ole sama, mis enne projekti väljatöötamise dokumendi kirjutamist projekti projekti tootekoodi kirjutamist. Ära tee seda. Kuid idee kinnitamiseks peaksite kindlasti kirjutama mõne häkilise koodi. Ainult uurimiskoodi kirjutamise tagamiseks muutke reegliks, et ükski selle prototüübi kood ei ühendata ülemkoodiks.

Pärast seda, kui teil on idee, kuidas oma projektiga edasi minna, toimige järgmiselt:

  1. Küsige oma meeskonnalt kogenud inseneri või tehnilise juhtkonna arvustust. Ideaalis oleks see keegi, keda austatakse ja / või kes on tuttav probleemi äärmuslike juhtumitega. Altkäemaks neid vajadusel bobaga.
  2. Minge tahvliga konverentsiruumi.
  3. Kirjeldage probleemi, millega selle inseneri poole pöördute (see on väga oluline samm, ärge jätke seda vahele!).
  4. Seejärel selgitage oma rakendamist ja veenge neid, et see on õige asi.

Kui te kõik seda teete enne, kui hakkate isegi oma disainidokumenti kirjutama, saate tagasisidet nii kiiresti kui võimalik, enne kui investeerite rohkem aega ja olete konkreetse lahendusega seotud. Isegi kui rakendamine jääb samaks, oskab teie ülevaataja sageli välja tuua nurgatagused juhtumid, mida peate katma, osutama võimalikele segadusaladele ja prognoosima raskusi, millega võite hiljem kokku puutuda.

Kui olete oma kujundusdokumendi ligikaudse kavandi juba kirjutanud, laske samal retsensendil see uuesti läbi lugeda ja tembeldage see ümber, lisades nende nime ülevaatajana kujundusdokumendi jaotisesse Pealkiri ja inimesed. See loob retsensendile täiendava stiimuli ja vastutuse.

Selle märkuse jaoks võiksite kaaluda disaini konkreetsete aspektide jaoks spetsiaalsete ülevaatajate (näiteks SRE-de ja turbeinseneride) lisamist.

Kui olete koos retsensendiga (autorid) registreerunud, saatke julgelt oma meeskonnale kujundusdokument, et saada tagasisidet ja jagada teadmisi. Pikaajaliste viivituste vältimiseks soovitan selle tagasiside kogumise ajaliselt piirata umbes ühe nädalaga. Pühenduge kõigile küsimustele ja kommentaaridele, mida inimesed selle nädala jooksul lahkuvad. Kommentaaride riputamine = halb karma.

Ja kui teie, teie retsensendi ja teiste dokumenti lugevate inseneride vahel on palju vaidlusi, soovitan tungivalt koondada kõik väited oma dokumendi jaotisesse Arutelu. Seejärel korraldage kohtumine erinevate osapooltega, et isiklikult nendest erimeelsustest rääkida.

Kui vestlusring on pikem kui 5 kommentaari, kipub isikliku vestluse juurde liikumine olema palju tõhusam. Pidage meeles, et ikkagi vastutate lõpliku kõne tegemise eest, isegi kui kõik ei jõua üksmeelele.

Hiljuti Shrey Bangaga sel teemal vesteldes sain teada, et Quipil on sarnane protsess, välja arvatud lisaks sellele, et teie meeskonnas on retsensendina kogenud insener või tehnikajuht, soovitavad nad lisaks lasta mõne muu meeskonna inseneril üle vaadata ka dokument. Ma pole seda proovinud, kuid näen kindlasti, et see aitab tagasisidet saada erinevate vaatenurkade alt ja parandada dokumendi üldist loetavust.

Kui olete kõik ülaltoodu teinud, on aeg asuda rakendamist alustama! Täiendavate küpsetuspunktide saamiseks käsitlege seda kujundusdokumenti disainilahenduse rakendamisel elava dokumendina. Uuendage dokumenti iga kord, kui saate teada midagi, mis tingib algses lahenduses muudatuste tegemise või toote ulatuse värskendamise. Tänate mind hiljem, kui te ei pea kõikidele sidusrühmadele asju ikka ja jälle seletama.

Lõpuks, saagem korraks tõeliselt meta: Kuidas me hindame disainidokumendi edukust?

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

  1. Veedate 5 päeva kujundusdokumendi kirjutamisel, see sunnib teid mõtlema läbi tehnilise arhitektuuri erinevad osad
  2. Saate arvustajatelt tagasisidet, et X on kavandatud arhitektuuri kõige ohtlikum osa
  3. Projekti riski vähendamiseks otsustate kõigepealt rakendada X
  4. 3 päeva hiljem saate aru, et X pole kas võimalik või on palju keerulisem, kui algselt kavatsesite
  5. Otsustate selle projekti kallal töötamise lõpetada ja eelistate selle asemel muud tööd

Selle artikli alguses ütlesime, et disainidokumendi eesmärk on veenduda, et õige töö saab tehtud. Ülaltoodud näites olete tänu sellele kujundusdokumendile kulutanud selle asemel, et potentsiaalselt mitu kuud vaid projekti hilisemaks katkestamiseks kulutada, olete veetnud ainult 8 päeva. Mulle tundub üsna edukas tulemus.

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

Krediidi andmine seal, kus krediiti tuleb maksta, õppisin palju eelnevat, tehes koostööd mõne uskumatu inseneri juures Plaidis (me võtame tööle! Tulge kujundage ja ehitage koos meiega mõned armsad tehnosüsteemid) ja Quorasse.

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