Kaip parašyti gerą programinės įrangos projektavimo dokumentą

Kaip programinės įrangos inžinierius daug laiko praleidžiu skaitydamas ir rašydamas projektinius dokumentus. Peržiūrėjęs šimtus šių dokumentų, iš pirmų lūpų mačiau tvirtą sąsają tarp gerų projektavimo dokumentų ir galutinės projekto sėkmės.

Šis straipsnis yra mano bandymas apibūdinti tai, kuo dizaino dokumentas yra puikus .

Straipsnis yra padalintas į 4 skyrius:

  • Kodėl reikia rašyti projektinį dokumentą
  • įtraukti į projekto dokumentą
  • Kaip tai parašyti
  • Procesas aplink jį

Kodėl reikia rašyti dizaino dokumentą?

Projektavimo dokumentas, dar vadinamas technine specifikacija, yra aprašymas, kaip planuojate išspręsti problemą.

Jau yra parašyta daugybė klausimų, kodėl prieš pradedant kodavimą svarbu parašyti dizaino dokumentą. Taigi viskas, ką čia pasakysiu, yra:

Dizaino dokumentas yra naudingiausia priemonė užtikrinant, kad bus atliktas tinkamas darbas.

Pagrindinis dizaino dokumento tikslas yra padaryti jus efektyvesnius, priverčiant jus apgalvoti dizainą ir rinkti kitų atsiliepimus. Žmonės dažnai mano, kad dizaino dokumento esmė yra mokyti kitus apie kokią nors sistemą arba vėliau būti dokumentais. Nors tai gali būti naudingas šalutinis poveikis, jie nėra savaiminis tikslas.

Paprastai dirbant su projektu, kuris gali užtrukti 1 ar daugiau inžinierių mėnesių, turėtumėte parašyti projektavimo dokumentą. Tačiau tuo nesustokite - daugeliui mažesnių projektų taip pat gali būti naudingas mini dizaino dokumentas.

Puiku! Jei vis dar skaitote, tikite dizaino dokumentų svarba. Tačiau skirtingos inžinierių komandos ir net tos pačios komandos inžinieriai projektavimo dokumentus dažnai rašo labai skirtingai. Taigi pakalbėkime apie gero dizaino dokumento turinį, stilių ir procesą.

Ką įtraukti į dizaino dokumentą?

Projektavimo dokumente aprašomas problemos sprendimas. Kadangi kiekviena problema yra skirtinga, savaime suprantama, kad norėtumėte skirtingai sukonstruoti savo dizaino dokumentą.

Norėdami pradėti, toliau pateikiamas skyrių, į kuriuos turėtumėte bent jau atsižvelgti, sąrašasįskaitant savo kitą dizaino dokumentą:

Pavadinimas ir žmonės

Jūsų dizaino dokumento pavadinimasautorius (-iai) (turėtų sutapti su žmonių, planuojančių dirbti prie šio projekto, sąrašu), recenzentas (-ai)dokumento (apie tai daugiau pakalbėsime toliau esančiame skyriuje „Procesas“) ir paskutinio šio dokumento atnaujinimo datą.

Apžvalga

Aukšto lygio santrauka, kurią kiekvienas įmonės inžinierius turėtų suprasti ir naudoti nuspręsdamas, ar jiems naudinga perskaityti likusį dokumentą. Tai turėtų būti ne daugiau kaip 3 pastraipos.

Kontekstas

Nagrinėjamos problemos aprašymas, kodėl šis projektas yra būtinas, ką žmonės turi žinoti, kad galėtų įvertinti šį projektą ir kaip jis atitinka techninę strategiją, produkto strategiją ar komandos ketvirčio tikslus.

Tikslai ir ne tikslai

Skiltyje „Tikslai“ turėtų būti:

  • apibūdinkite vartotojo suprojektuotą savo projekto poveikį - kur jūsų vartotojas gali būti kita inžinierių komanda ar net kita techninė sistema
  • nurodykite, kaip įvertinti sėkmę naudojant metriką - premijos taškai, jei galite susieti su informacijos suvestine, kuri stebi tą metriką

Ne tikslai yra vienodai svarbūs apibūdinant problemas, kurių neišspręsite, kad visi būtų tame pačiame puslapyje.

Etapai

Išmatuojamų kontrolinių punktų sąrašas, kad jūsų vadovas ir jūsų vadovo vadovas galėtų jį nugriebti ir apytiksliai žinoti, kada bus atliekamos skirtingos projekto dalys. Jei projektas yra ilgesnis nei 1 mėn., Raginu suskaidyti projektą į svarbiausius vartotojams skirtus etapus.

Naudokite kalendoriaus datas, kad atsižvelgtumėte į nesusijusius vėlavimus, atostogas, susitikimus ir pan. Tai turėtų atrodyti maždaug taip:

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

Pridėkite [Update]poskyrį čia, jei pasikeis kai kurių iš šių etapų ETA, kad suinteresuotosios šalys galėtų lengvai pamatyti naujausius įvertinimus.

Esamas sprendimas

Be dabartinio diegimo aprašymo, taip pat turėtumėte pereiti per aukšto lygio pavyzdinį srautą, kad parodytumėte, kaip vartotojai sąveikauja su šia sistema ir (arba) kaip duomenys joje teka.

vartotojasistorijayra puikus būdas tai įrėminti. Atminkite, kad jūsų sistemoje gali būti skirtingų tipų naudotojai, turintys skirtingus naudojimo atvejus.

Pasiūlytas sprendimas

Kai kurie žmonės tai vadina skyriumi „ Techninė architektūra“ . Vėl pabandykite pereiti vartotojo istoriją, kad tai sukonkretintumėte. Nedvejodami įtraukite daug poskyrių ir diagramų.

Pirmiausia pateikite bendrą vaizdą, tada užpildykite partijasapiedetales. Siekite pasaulio, kuriame galite tai parašyti, tada atostogaukite kokioje nors apleistoje saloje, o kitas komandos inžinierius gali tiesiog ją perskaityti ir įgyvendinti sprendimą, kaip aprašėte.

Alternatyvūs sprendimai

Ką dar svarstėte, kai pateikėte pirmiau pateiktą sprendimą? Kokie yra alternatyvų pliusai ir minusai? Ar svarstėte pirkti trečiosios šalies sprendimą - ar naudoti atvirojo kodo sprendimą - kuris išspręstų šią problemą, o ne kurtų savo?

Testavimas, stebėjimas ir įspėjimas

Man patinka įtraukti šį skyrių, nes žmonės dažnai tai traktuoja kaip nepagalvotą dalyką arba praleidžia visa tai kartu, ir tai beveik visada grįžta vėliau jiems įkandant, kai viskas nutrūksta ir jie neįsivaizduoja, kaip ir kodėl.

Kryžminis komandos poveikis

Kaip tai padidins skambučių ir „dev-ops“ našta?

Kiek tai kainuos?

Ar tai sukelia sistemos vėlavimo regresiją?

Ar tai atskleidžia saugumo spragas?

Kokios yra neigiamos pasekmės ir šalutinis poveikis?

Kaip palaikymo komanda galėtų tai pranešti klientams?

Atviri klausimai

Visi atviri klausimai, dėl kurių nesate tikri, ginčytini sprendimai, kuriuos norite skaitytojams pasverti, siūlomi darbai ateityje ir pan. Šios dalies pavadinimas liežuviu į skruostą yra „žinomi nežinomi“.

Išsamus aprėptis ir laiko juosta

Šį skyrių dažniausiai skaitys tik prie šio projekto dirbantys inžinieriai, jų vadovai technologijoms ir jų vadovai. Taigi šis skyrius yra dok. Pabaigoje.

Iš esmės tai yra suskirstymas į tai, kaip ir kada planuojate vykdyti kiekvieną projekto dalį. Tiksliai nustatoma daugybė sričių, todėl galite perskaityti šį įrašą, kad sužinotumėte daugiau apie taikymo sritį.

Aš taip pat linkęs traktuoti šį projektavimo dokumento skyrių kaip vykdomą projekto užduočių stebėjimo priemonę, todėl atnaujinu tai, kai pasikeičia mano taikymo srities įvertinimas. Bet tai labiau asmeniniai pageidavimai.

Kaip tai parašyti

Dabar, kai jau kalbėjome apie tai, kas yra geras dizaino dokumentas, pakalbėkime apie rašymo stilių. Pažadu, kad tai kitoks nei tavo vidurinės anglų kalbos klasė.

Rašykite kuo paprasčiau

Nebandykite rašyti taip, kaip skaityti akademiniai darbai. Jie parašyti tam, kad sužavėtų žurnalų apžvalgininkus. Jūsų dokumentas parašytas siekiant apibūdinti jūsų sprendimą ir gauti atsiliepimų iš komandos draugų. Aiškumo galite pasiekti naudodami:

  • Paprasti žodžiai
  • Trumpi sakiniai
  • Sąrašai su ženkleliais ir (arba) sunumeruoti sąrašai
  • Konkretūs pavyzdžiai, pvz., „Vartotoja Alisa susieja savo banko sąskaitą, tada ...“

Pridėkite daug diagramų ir diagramų

Diagramos dažnai gali būti naudingos norint palyginti keletą galimų variantų, o diagramas paprastai lengviau analizuoti nei tekstą. Man sekėsi kurti „Google Drawing“ kuriant diagramas.

„Pro“ patarimas: nepamirškite pridėti nuorodos į redaguojamą schemos versiją po ekrano kopija, kad vėliau galėtumėte lengvai ją atnaujinti, kai viskas neišvengiamai pasikeis.

Įtraukite skaičius

Problemos mastas dažnai lemia sprendimą. Norėdami padėti apžvalgininkams suvokti pasaulio būseną, įtraukite realius skaičius, pvz., DB eilučių, # vartotojo klaidų, delsos laiką ir tai, kaip jie keičiami naudojant. Prisimeni savo „Big-O“ užrašus?

Pasistenkite būti juokingi

Specifikacija nėra akademinis darbas. Be to, žmonėms patinka skaityti juokingus dalykus, todėl tai yra geras būdas palaikyti skaitytoją. Nepersistenkite taip, kad neatsižvelgtumėte į pagrindinę idėją.

Jei jums, kaip ir man, yra sunku juokauti, Joelis Spolsky ( akivaizdžiai žinomas dėl savo komiškų talentų ...) turi šį patarimą:

Vienas iš paprasčiausių būdų būti linksmam yra konkretus, kai to nereikia [… Pavyzdys:] Užuot sakę „specialūs interesai“, pasakykite „kairiarankiai avakadų augintojai“.

Atlikite skepticizmo testą

Prieš siųsdami savo dizaino dokumentą kitiems peržiūrėti, apsimeskite jį apsimetę recenzentu. Kokie klausimai ir abejonės gali kilti dėl šio dizaino? Tada kreipkitės į juos prevenciškai.

Atlikite atostogų testą

Jei dabar einate ilgų atostogų be interneto prieigos, ar kas nors iš jūsų komandos gali perskaityti dokumentą ir jį įgyvendinti taip, kaip ketinote?

Pagrindinis dizaino dokumento tikslas nėra dalijimasis žiniomis, tačiau tai yra geras būdas įvertinti aiškumą, kad kiti iš tikrųjų galėtų suteikti jums naudingų atsiliepimų.

Procesas

Ak taip, bijotas P-žodis . Dizaino dokumentai padeda gauti grįžtamąjį ryšį, prieš sugaišdami daugybę laiko įgyvendindami netinkamą arba netinkamos problemos sprendimą. Norint gauti gerų atsiliepimų, reikia daug meno, tačiau tai skirta vėlesniam straipsniui. Kol kas pakalbėkime konkrečiai apie tai, kaip parašyti dizaino dokumentą ir gauti apie jį atsiliepimų.

Visų pirma, visi, dirbantys prie projekto, turėtų būti projektavimo proceso dalyviai. Gerai, jei pirmaujanti technologija paskatins priimti daugybę sprendimų, tačiau visi turėtų dalyvauti diskusijoje ir įsitraukti į dizainą. Taigi „jūs“ šiame straipsnyje yra tikrai daugiskaitos „jūs“, apimantis visus projekto žmones.

Antra, projektavimo procesas nereiškia, kad žiūrite į lentą, kur teorijos teorijos. Drąsiai susitepkite rankas ir prototipuokite galimus sprendimus. Tai nėra tas pats, kas pradėti rašyti projekto gamybos kodą prieš rašant dizaino dokumentą. Nedaryk to. Bet jūs tikrai turėtumėte drąsiai parašyti nulaužtą metimo kodą, kad patvirtintumėte idėją. Norėdami užtikrinti, kad rašote tik tiriamąjį kodą, nustatykite taisyklę, kad nė vienas šio prototipo kodas nebus sujungtas su pagrindiniu .

Po to, kai pradėsite galvoti apie savo projekto įgyvendinimą, atlikite šiuos veiksmus:

  1. Paprašykite patyrusio inžinieriaus ar savo komandos lyderio būti jūsų apžvalgininku. Idealiu atveju tai būtų tas žmogus, kuris yra gerai gerbiamas ir (arba) yra susipažinęs su svarbiausiais problemos atvejais. Jei reikia, papirkite juos boba.
  2. Eik į konferencijų salę su lenta.
  3. Apibūdinkite problemą, kurią sprendžiate šiam inžinieriui (tai labai svarbus žingsnis, nepraleiskite jo!).
  4. Tada paaiškinkite savo turimą įgyvendinimą ir įtikinkite juos, kad tai yra teisingas dalykas.

Daro visa tai prieš jus net pradėti rašyti savo dizainą doc leidžia gauti grįžtamąjį ryšį, kai tik įmanoma, prieš jus investuoti daugiau laiko ir gauti prijungtas prie bet kokio konkretaus sprendimo. Dažnai, net jei įgyvendinimas lieka nepakitęs, jūsų apžvalgininkas gali nurodyti kampinius atvejus, kuriuos turite aprėpti, nurodyti galimas painiavos sritis ir numatyti sunkumus, su kuriais vėliau gali susidurti.

Tada, parašę apytikslį savo dizaino dokumento juodraštį, paprašykite to paties recenzento dar kartą jį perskaityti ir guminiu antspaudu pridėdami savo, kaip recenzento, vardą dizaino dokumento skyriuje Pavadinimas ir žmonės . Tai sukuria papildomą paskatą ir atskaitomybę recenzentui.

Atsižvelgdami į tai, apsvarstykite galimybę įtraukti specialius recenzentus (pvz., SRE ir saugumo inžinierius) dėl konkrečių projekto aspektų.

Kai jūs ir recenzentas (-ai) atsijungs, nedvejodami atsiųskite dizaino dokumentą savo komandai, kad gautumėte papildomų atsiliepimų ir pasidalintumėte žiniomis. Siūlau šį grįžtamojo ryšio rinkimo procesą apriboti maždaug viena savaite, kad būtų išvengta ilgesnio vėlavimo. Įsipareigokite spręsti visus klausimus ir komentarus, kuriuos žmonės palieka per tą savaitę. Palikti kabančius komentarus = bloga karma.

Galiausiai, jei tarp jūsų, recenzento ir kitų inžinierių, skaitančių dokumentą, kyla daug ginčų, labai rekomenduoju visus ginčo dalykus įtvirtinti jūsų dokumento skyriuje „ Diskusijos“ . Tada surenkite susitikimą su skirtingomis šalimis, kad galėtumėte asmeniškai aptarti šiuos nesutarimus.

Kai diskusijų tema yra ilgesnė nei 5 komentarai, pereiti prie asmeninės diskusijos būna daug efektyvesnė. Turėkite omenyje, kad vis tiek esate atsakingas už paskutinio skambučio atlikimą, net jei visi negali susitarti.

Neseniai apie tai kalbėdamasis su Shrey Banga sužinojau, kad „Quip“ procesas yra panašus, išskyrus tai, kad jūsų komandoje, kaip recenzentui, vadovauja patyręs inžinierius ar technikos vadovas, jie taip pat siūlo, kad kitos komandos inžinierius peržiūrėtų dokumentą. Aš to nebandžiau, bet tikrai matau, kad tai padeda gauti skirtingų perspektyvų žmonių atsiliepimus ir pagerinti bendrą dok. Skaitomumą.

Atlikę viską, kas išdėstyta pirmiau, laikas pradėti diegti! Norėdami gauti papildomų taškų ant rudos spalvos, įgyvendinkite dizainą laikykite šį dizaino dokumentą kaip gyvą dokumentą . Atnaujinkite dokumentą kiekvieną kartą, kai sužinosite ką nors, kas paskatins pakeisti pirminį sprendimą arba atnaujinsite taikymo sritį. Padėkosite man vėliau, kai jums nereikės visko aiškinti visoms savo suinteresuotosioms šalims.

Galiausiai, paimkime iš tikrųjų metą sekundei: Kaip mes vertiname dizaino dokumento sėkmę?

Mano bendradarbis Kentas Rakipas turi gerą atsakymą į tai: dizaino dokumentas yra sėkmingas, jei atliekama tinkama darbo IG. Tai reiškia, kad sėkmingas dizaino dokumentas iš tikrųjų gali sukelti tokį rezultatą:

  1. Jūs praleidžiate 5 dienas rašydami projektavimo dokumentą, tai priverčia jus apgalvoti įvairias techninės architektūros dalis
  2. Gaunate apžvalgininkų atsiliepimų, kurie Xyra rizikingiausia siūlomos architektūros dalis
  3. Jūs nusprendžiate įgyvendinti Xpirmiausia, kad sumažintumėte projekto riziką
  4. Praėjus 3 dienoms Xsuprantate , kad tai neįmanoma arba kur kas sunkiau, nei iš pradžių ketinote
  5. Nusprendžiate nebedirbti su šiuo projektu ir pirmenybę teikiate kitiems darbams

Šio straipsnio pradžioje mes pasakėme, kad dizaino dokumento tikslas yra įsitikinti, ar atliktas tinkamas darbas. Ankstesniame pavyzdyje, dėka šio dizaino dokumento, užuot sugaištę mėnesius tik tam, kad vėliau nutrauktumėte šį projektą, jūs praleidote tik 8 dienas. Man atrodo, kad tai gana sėkmingas rezultatas.

Prašome palikti komentarą žemiau, jei turite klausimų ar atsiliepimų! Taip pat norėčiau išgirsti apie tai, kaip jūsų komandoje skirtingai kuriate dizaino dokumentus.

Suteikdamas kreditą ten, kur priklauso kreditas, aš išmokau daugelio aukščiau išvardytų dalykų dirbdamas kartu su keliais neįtikėtinais inžinieriais „Plaid“ (mes samdome! Ateikite su mumis kurti ir pastatyti saldžių techninių sistemų) ir „Quora“.

Jei jums patinka šis įrašas, sekite mane „Twitter“ ir gaukite daugiau įrašų apie inžineriją, procesus ir vidines sistemas.