Angela Zhang
ohjelmistosuunnittelijana, en viettää paljon aikaa lukemisen ja kirjoittamisen suunnittelu asiakirjoja. Kun olen käynyt läpi satoja näitä docs, olen nähnyt ensi käden vahva korrelaatio hyvän suunnittelun docs ja lopullinen menestys projektin.
Tämä artikkeli on yritykseni kuvata, mikä tekee suunnitteludokumentista mahtavan.,
artikkeli on jaettu 4 kohdat:
- Miksi kirjoittaa design asiakirja
- Mitä sisällyttää suunnittelu-dokumentti
- Miten kirjoittaa se
- prosessin sen ympärille
Miksi kirjoittaa design asiakirja?
suunnitteludokumentti-joka tunnetaan myös teknisenä erikoisuutena-on kuvaus siitä, miten aiot ratkaista ongelman.
jo nyt on paljon kirjoituksia siitä, miksi on tärkeää kirjoittaa suunnittelutohtori ennen koodaukseen sukeltamista. Joten kaikki mitä voin sanoa on:
design-doc on hyödyllisin työkalu varmista oikea työ tulee tehdyksi.,
suunnittelutohtorin päätavoitteena on tehdä sinusta tehokkaampi pakottamalla sinut miettimään suunnittelua ja keräämään palautetta muilta. Usein ajatellaan, että suunnittelulääkärin tarkoitus on opettaa toisille jotakin järjestelmää tai toimia dokumentaationa myöhemmin. Vaikka ne voivat olla hyödyllisiä sivuvaikutuksia, ne eivät ole tavoite itsessään.
yleisenä nyrkkisääntönä, jos olet työskennellyt projekti, joka saattaa kestää 1-insinööri kuukauden tai enemmän, sinun pitäisi kirjoittaa suunnittelu asiak. Mutta älä lopeta siihen — monet pienemmät projektit voisivat hyötyä mini design doc liian.
Great!, Jos vielä luet, uskot design Docsin tärkeyteen. Kuitenkin eri insinööritiimit ja jopa saman tiimin insinöörit kirjoittavat usein suunnittelulokeroita hyvin eri tavalla. Joten puhutaan sisällöstä, tyyli, ja prosessi hyvä muotoilu doc.
Mitä sisällyttää suunnittelu, doc?
a design doc kuvaa ratkaisua ongelmaan. Koska luonne kunkin ongelman on erilainen, luonnollisesti haluat jäsentää suunnittelun doc eri tavalla.,
aloittaa, seuraava on luettelo kohdat, jotka sinun pitäisi ainakin harkita myös seuraavan suunnittelu doc:
Otsikko ja Ihmiset
otsikko suunnittelua tohtori, kirjailija(s) (pitäisi olla sama kuin luettelo ihmiset haluavat työtä tämän projektin kanssa), arvioija(t) doc (me puhua enemmän siitä, että Prosessi jakso jäljempänä), ja, jona tämä asiakirja on viimeksi päivitetty.
yleiskatsaus
korkean tason yhteenveto, joka jokaisen yrityksen insinöörin pitäisi ymmärtää ja käyttää päättääkseen, onko heidän hyödyllistä lukea loput doc., Sen pitäisi olla 3 kappaletta max.
Yhteydessä
kuvaus ongelmaan, miksi tämä hanke on tarpeellinen, mitä ihmisten täytyy tietää arvioimaan tätä hanketta, ja miten se sopii osaksi tekninen strategia, tuote strategia, tai joukkueen neljännesvuosittain tavoitteita.,
Tavoitteet ja Ei-Tavoitteet
– Tavoitteet, kohta olisi:
- kuvataan käyttäjälähtöinen vaikutus projektin—, jossa käyttäjä voi olla toinen suunnittelutiimi tai jopa toinen tekninen järjestelmä
- määrittää, miten mitata menestystä käyttämällä mittareita — bonus pisteitä, jos voit linkittää kojelauta, joka seuraa näitä mittareita
Ei-Tavoitteet ovat yhtä tärkeitä kuvaamaan, mitä ongelmia sinulla ei ole e, joten jokainen on samalla sivulla.,
Virstanpylväät
luettelo mitattavissa olevia tarkastuspisteitä, joten PM ja esimiehesi esimies voi lukaista se ja tietää suunnilleen, kun hankkeen eri osien tulee olla valmis. Kannustan sinua purkamaan projektin suuriksi käyttäjien kohtaamiksi virstanpylväiksi, jos projekti on yli kuukauden mittainen.
Käytä päivämääriä, joten voit ottaa huomioon liity viivästyksiä, lomat, kokoukset ja niin edelleen., Sen pitäisi näyttää tältä:
Start Date: June 7, 2018Milestone 1 — New system MVP running in dark-mode: June 28, 2018Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018
Lisää yksi alaluokka täällä, jos ETA jotkut näistä virstanpylväs muutoksia, joten sidosryhmät voivat helposti nähdä kaikkein up-to-date arviot.
Olemassa Ratkaisu
lisäksi kuvataan nykyinen toteutus, sinun pitäisi myös kulkea korkean tason esimerkki virtausta kuvaavat, kuinka käyttäjät ovat vuorovaikutuksessa järjestelmän ja/tai miten tietovirta läpi.,
käyttäjätarina on oiva tapa kehystää tätä. Muista, että järjestelmä voi olla erityyppisiä käyttäjiä eri käyttötapauksia.
Ehdotettu Ratkaisu
Jotkut ihmiset kutsuvat tätä Tekninen Arkkitehtuuri-osiossa. Jälleen, yritä kävellä läpi käyttäjän tarina konkretize tätä. Voit vapaasti sisällyttää monia alaosioita ja kaavioita.
antaa ensin ison kuvan, sitten täyttää paljon yksityiskohtia. Tavoitteena on maailma, jossa voit kirjoittaa tämän, sitten ottaa lomaa jossain autiolla saarella, ja toinen insinööri joukkue voi vain lukea se ja toteuttaa ratkaisu, kuin kuvailit.,
Vaihtoehtoisia Ratkaisuja
– Mitä muuta voit harkita, kun keksiä ratkaisu edellä? Mitkä ovat vaihtoehtojen hyvät ja huonot puolet? Oletko harkinnut ostavasi kolmannen osapuolen ratkaisun — tai avoimen lähdekoodin ratkaisun — joka ratkaisee tämän ongelman sijaan rakentaa oman?
Testattavuus, Valvonta ja Hälytys
pidän myös tässä osiossa, koska ihmiset usein kohtelevat tätä kuin jälkikäteen tai ohittaa sen kaikki yhdessä, ja se melkein aina tulee takaisin purra niitä myöhemmin, kun asiat rikkoa ja he eivät tiedä, miten tai miksi.,
Cross-Joukkue Vaikuttaa
Miten tämä kasvu on call-ja dev-ops taakka?
paljonko se maksaa?
aiheuttaako se systeemiin latenssirepressiota?
paljastaako se tietoturvahaavoittuvuuksia?
mitkä ovat joitakin kielteisiä seurauksia ja sivuvaikutuksia?
miten tukitiimi voisi viestiä asiasta asiakkaille?
Kysymyksiä
avoimia kysymyksiä, että et ole varma noin, kiistanalaisia päätöksiä, jotka haluat lukijat punnita, ehdotti, että tulevaisuudessa työtä, ja niin edelleen. Kieli poskessa-nimi tälle osiolle on ”tunnetut tuntemattomat”.,
Yksityiskohtainen Rajaus ja aikataulu
Tämä osio on enimmäkseen tulee lukea vain insinöörit työskentelevät tämän projektin, niiden teknologia johtaa, ja niiden johtajat. Näin ollen tämä osa on lopussa doc.
Pohjimmiltaan, tässä on erittely siitä, miten ja milloin aiot suorittamista jokaisella osa hanketta. On paljon, joka menee scoping tarkasti, joten voit lukea tämän viestin oppia lisää scoping.
minulla on taipumus käsitellä myös tätä design doc: n osiota jatkuvana projektitehtävien seurantana, joten päivitän tätä aina, kun arvioni muuttuu., Mutta se on enemmän henkilökohtainen mieltymys.
Miten kirjoittaa se
Nyt kun olemme puhuneet siitä, mitä menee hyvä suunnittelu doc, puhutaanpa tyyli kirjoittaa. Lupaan, että tämä on eri asia kuin englannin lukiosi.
kirjoita mahdollisimman yksinkertaisesti
älä yritä kirjoittaa kuin lukemasi akateemiset paperit. Ne on kirjoitettu tekemään vaikutuksen lehden arvostelijoihin. Doc on kirjoitettu kuvaamaan ratkaisuasi ja saada palautetta joukkuetovereiltasi., Voit saavuttaa selkeyden käyttämällä:
- Yksinkertaisia sanoja
- Lyhyet lauseet
- Numeroimattomia luetteloita ja/tai numeroituja luetteloita
- Konkreettisia esimerkkejä, kuten ”Käyttäjän Alice yhdistää hänen pankki-tilille, niin …”
Lisää paljon kaavioita ja kaavioita
Kaavioita voi usein olla hyödyllistä vertailla useita mahdollisia vaihtoehtoja, ja kaaviot ovat yleensä helpompi jäsentää kuin teksti. Olen ollut onnea Google piirustus luoda kaavioita.,
Pro Vihje: muista lisätä linkki kaavion muokattavaan versioon kuvakaappauksen alla, joten voit päivittää sen helposti myöhemmin, kun asiat väistämättä muuttuvat.
sisältävät numerot
ongelman mittakaava määrittää usein ratkaisun. Auttaakseen arvostelijoita saamaan käsityksen maailman tilasta, sisältävät reaalilukuja, kuten # DB-rivejä, # käyttäjävirheitä, latenssia-ja miten nämä mittakaavat käytön kanssa. Muistatteko Isot notaationne?
Try to be funny
a spec is not an academic paper. Myös ihmiset tykkäävät lukea hauskoja juttuja, joten tämä on hyvä tapa pitää lukija mukana., Älä kuitenkaan liioittele tätä niin, että ottaisit ydinajatuksen pois.
Jos et, kuten minä, on vaikea olla hauska, Joel Spolsky (ilmeisesti tunnettu hänen comedic kykyjä…) tässä on vihje:
Yksi helpoimmista tavoista hauskaa on olla erityinen, kun se ei ole vaati sen Sijaan, että sanonta ”erityisiä etuja,” sanoa ”vasenkätinen avacado viljelijät.”
Onko Skeptikko Testi
Ennen kuin lähetät suunnittelu doc muiden arvostelu, menisi samalla se teeskentelee olevansa arvostelija. Mitä kysymyksiä ja epäilyksiä sinulla voisi olla tästä suunnitelmasta?, Puhuttele heitä ennalta.
Do the Vacation Test
Jos lähdet pitkälle lomalle nyt ilman nettiyhteyttä, voiko joku tiimistäsi lukea tohtorin ja toteuttaa sen tarkoitetulla tavalla?
suunnittelutohtorin päätavoite ei ole tiedon jakaminen, mutta tämä on hyvä tapa arvioida selkeyttä, jotta muut voivat oikeasti antaa hyödyllistä palautetta.
Prosessi
Ah kyllä, pelätty P-sana., Design docs auttaa sinua saamaan palautetta ennen kuin tuhlaat paljon aikaa väärän ratkaisun tai väärän ongelman ratkaisun toteuttamiseen. Hyvän palautteen saamiseen on paljon taidetta, mutta se on myöhempää artikkelia varten. Toistaiseksi, puhutaan vain erityisesti siitä, miten kirjoittaa suunnittelun doc ja saada palautetta siitä.
ensinnäkin jokaisen projektin parissa työskentelevän tulisi olla osa suunnitteluprosessia. Se on okei, jos tech johtaa päätyy ajo paljon päätöksiä, mutta kaikkien pitäisi olla mukana keskustelussa ja ostaa suunnitteluun., Joten ”sinä” koko tämän artikkelin on todella monikossa ”sinä”, joka sisältää kaikki ihmiset projektin.
toiseksi suunnitteluprosessi ei tarkoita sitä, että tuijottaisit valkotauluteoreettisia ideoita. Voit vapaasti saada kädet likainen ja prototyyppi mahdollisia ratkaisuja. Tämä ei ole sama asia kuin alkaa kirjoittaa projektiin tuotantokoodia ennen design Docin kirjoittamista. Älä tee noin. Mutta sinun ehdottomasti pitäisi vapaasti kirjoittaa joitakin hacky throwaway koodi vahvistaa idea., Varmistaaksesi, että kirjoitat vain tunnustelukoodin, tee siitä sääntö, että mikään prototyyppikoodista ei yhdisty Masteriin.
sen Jälkeen, kun alkaa olla jonkinlainen käsitys siitä, miten projekti, toimi seuraavasti:
- Kysy kokenut insinööri tai tech johtaa tiimisi on sinun arvostelija. Ihannetapauksessa tämä olisi joku, joka on hyvin arvostettu ja/tai perehtynyt reuna tapauksissa ongelma. Lahjoa heidät tarvittaessa boballa.
- mene kokoushuoneeseen, jossa on taulu.,
- Kuvaile ongelma, että olet puuttumalla tähän insinööri (tämä on erittäin tärkeä askel, älä ohita sitä!).
- selitä sitten mielessäsi oleva toteutus ja vakuuta heille, että tämä on oikea asia rakentaa.
Doing kaikki tämä ennen kuin edes alkaa kirjoittaa oman suunnittelun doc avulla voit saada palautetta niin pian kuin mahdollista, ennen kuin sijoittaa enemmän aikaa ja saada kiinni mitään tiettyä ratkaisua., Usein, vaikka täytäntöönpano pysyy samana, sinun arvostelija pystyy huomauttaa nurkkaan tapauksissa sinun täytyy kattaa, osoittavat mahdollisia alueita sekaannusta, ja ennakoida ongelmia, joita saatat kohdata myöhemmin.
Sitten, kun olet kirjoittanut karkea luonnos oman suunnittelun doc, saada sama arvostelija lukemaan läpi uudelleen, ja kumileimasin sitä lisäämällä heidän nimensä arvostelija Otsikko ja Ihmiset jakso suunnittelu asiak. Tämä lisää arvostelijalle kannustimia ja vastuuvelvollisuutta.,
harkitse tässä huomautuksessa erikoistuneiden tarkastajien (kuten SREs: n ja turvallisuusinsinöörien) lisäämistä suunnittelun erityisnäkökohtiin.
Kun sinun ja arvostelija(t) merkki pois, voit vapaasti lähettää suunnittelu doc joukkue lisää palautetta ja tiedon jakaminen. Ehdotan, että tämä palautekeräys siirretään noin 1 viikkoon, jotta vältytään pitkiltä viivästyksiltä. Sitoudu vastaamaan kaikkiin kysymyksiin ja kommentteihin, jotka ihmiset lähtevät kyseisen viikon kuluessa. Leaving comments hanging = huono karma.,
Lopuksi, jos siellä on paljon kiistaa välillä, teidän arvostelija, ja muut insinöörit lukea doc, suosittelen konsolidointiryhmän kaikki kiistakysymyksiin Keskustelussa osa asiak. Sitten perustaa kokouksen eri osapuolten puhua näistä erimielisyyksistä henkilökohtaisesti.
Kun keskusteluketju on yli 5 kommentit pitkä, siirtymässä henkilökohtaista keskustelua on yleensä paljon tehokkaampaa. Muista, että olet edelleen vastuussa lopullisen puhelun soittamisesta, vaikka kaikki eivät pääsisikään yksimielisyyteen.,
puhua Shrey Banga viime aikoina tästä, olen oppinut, että Quip on samanlainen prosessi, lukuun ottamatta sen lisäksi, että kokenut insinööri tai tech johtaa tiimisi kuin arvostelija, ne viittaavat myös siihen, että insinööri on eri joukkue tarkistaa asiak. En ole kokeillut tätä, mutta näen varmasti tämän auttavan saamaan palautetta ihmisiltä, joilla on erilaisia näkökulmia ja parantamaan tohtorin yleistä luettavuutta.
Kun olet tehnyt kaiken edellä mainitun, aika lähteä toteuttamaan!, Lisää brownie pistettä, kohdella tätä design doc kuin elävä asiakirja, kun toteutat suunnittelu. Päivitä doc joka kerta, kun opit jotain, joka johtaa sinut tekemään muutoksia alkuperäiseen ratkaisuun tai päivittää scoping. Kiität minua myöhemmin, kun sinun ei tarvitse selittää asioita yhä uudelleen kaikille sidosryhmillesi.
– Nyt lähdetään todella meta toinen: Miten arvioida onnistumista suunnittelu doc?
työkaverillani Kent Rakipilla on tähän hyvä vastaus: muotoilulääkäri onnistuu, jos työn oikea ROI tehdään.,ts tekninen arkkitehtuuri
X on vaarallisin osa ehdotettu arkkitehtuuriX ensimmäinen de-risk-projektiX ei joko ole mahdollista, tai paljon vaikeampaa kuin alun perin tarkoitettu– alussa tämän artikkelin, me sanoi tavoite suunnittelu doc on varmistaa, että oikea työ tulee tehdyksi., Yllä olevassa esimerkissä, kiitos tämän suunnittelun doc, sen sijaan tuhlaa mahdollisesti kuukausia vain keskeyttää tämän projektin myöhemmin, olet viettänyt vain 8 päivää. Minusta se vaikuttaa onnistuneelta tulokselta.
jätä kommentti alle, jos sinulla on kysyttävää tai palautetta! Haluaisin kuulla myös siitä, miten suunnittelet dokumentteja eri tavalla tiimissäsi.
kunnian antaminen sille, mistä kunnia kuuluu, opin paljon edellä mainituista työskentelemällä yhdessä joidenkin uskomattoman insinöörien kanssa Plaidissa(me palkkaamme! Tule suunnittelemaan ja rakentamaan joitakin makeita teknisiä järjestelmiä kanssamme) ja Quora.,
Jos pidät tästä viestistä, seuraa minua Twitterissä saadaksesi lisää viestejä teknisistä, prosesseista ja taustajärjestelmistä.