Kuinka kirjoittaa hyvä ohjelmistosuunnitteluasiakirja

Ohjelmistoinsinöörinä vietän paljon aikaa suunnitteluasiakirjojen lukemiseen ja kirjoittamiseen. Kun olen käynyt läpi satoja näitä asiakirjoja, olen nähnyt omakohtaisesti vahvan korrelaation hyvien suunnitteludokumenttien ja projektin lopullisen menestyksen välillä.

Tämä artikkeli on yritykseni kuvata, mikä tekee suunnitteludokumentista suuren .

Artikkeli on jaettu 4 osaan:

  • Miksi kirjoittaa suunnitteluasiakirja
  • Mitä sisällyttää suunnitteluasiakirjaan
  • Kuinka kirjoittaa se
  • Prosessi ympärillä

Miksi kirjoittaa suunnitteluasiakirja?

Suunnitteludokumentti - joka tunnetaan myös nimellä tekninen eritelmä - on kuvaus ongelman ratkaisemisesta.

Jo nyt on paljon kirjoituksia siitä, miksi on tärkeää kirjoittaa suunnitteludokumentti ennen koodaamiseen sukeltamista. Joten kaikki mitä sanon tässä on:

Suunnitteludokumentti on hyödyllisin työkalu oikean työn varmistamiseksi.

Suunnitteludokumentin päätavoitteena on tehdä sinusta tehokkaampi pakottamalla sinut miettimään muotoilua ja keräämään palautetta muilta. Ihmiset ajattelevat usein, että suunnitteludokumentin tarkoitus on opettaa muille jostakin järjestelmästä tai toimia myöhemmin dokumentaationa. Vaikka nämä voivat olla hyödyllisiä sivuvaikutuksia, ne eivät ole itsessään päämäärä.

Nyrkkisääntönä on, että jos työskentelet projektissa, joka voi kestää vähintään yhden insinöörikuukauden, sinun tulee kirjoittaa suunnitteludokumentti. Mutta älä pysähdy siihen - monet pienemmät projektit voisivat hyötyä myös pienestä suunnitteludokumentista.

Loistava! Jos luet edelleen, uskot suunnitteludokumenttien tärkeyteen. Eri suunnittelutiimit ja jopa saman tiimin insinöörit kirjoittavat kuitenkin usein suunnitteluasiakirjat hyvin eri tavalla. Joten puhutaan hyvän suunnitteludokumentin sisällöstä, tyylistä ja prosessista.

Mitä sisällyttää suunnitteludokumenttiin?

Suunnitteludokumentti kuvaa ongelman ratkaisun. Koska jokaisen ongelman luonne on erilainen, haluat luonnollisesti rakentaa suunnitteludokumentin eri tavalla.

Seuraavassa on luettelo osioista, jotka sinun tulisi ainakin harkitamukaan lukien seuraava suunnitteludokumenttisi:

Otsikko ja ihmiset

Suunnitteludokumentin otsikkotekijä (t) (pitäisi olla sama kuin luettelo henkilöistä, jotka aikovat työskennellä tämän projektin parissa), arvioija (t)dokumentista (puhumme siitä tarkemmin alla olevassa Prosessiosassa) ja päivämäärä, jolloin tämä asiakirja viimeksi päivitettiin.

Yleiskatsaus

Korkean tason yhteenveto, jonka jokaisen yrityksen insinöörin tulisi ymmärtää ja käyttää päättääkseen, onko heille hyödyllistä lukea muu asiakirja. Sen tulisi olla enintään 3 kappaletta.

Asiayhteys

Kuvaus käsillä olevasta ongelmasta, miksi tämä projekti on tarpeen, mitä ihmisten on tiedettävä arvioidakseen tätä projektia ja miten se sopii tekniseen strategiaan, tuotestrategiaan tai tiimin neljännesvuositavoitteisiin.

Maalit ja ei-tavoitteet

Tavoitteet-osion tulisi:

  • kuvaile projektisi käyttäjälähtöistä vaikutusta - missä käyttäjäsi voi olla toinen suunnittelutiimi tai jopa toinen tekninen järjestelmä
  • määritä kuinka mitata menestystä mittareiden avulla - bonuspisteitä, jos voit linkittää koontinäyttöön, joka seuraa näitä tietoja

Non-tavoitteet ovat yhtä tärkeitä kuvailla mikä ongelmien ei voida vahvistaa niin kaikki ovat samalla sivulla.

Virstanpylväät

Luettelo mitattavissa olevista tarkistuspisteistä, jotta pääministerisi ja esimiehesi johtaja voivat ohittaa sen ja tietää karkeasti, milloin projektin eri osat tehdään. Kehotan teitä jakamaan projektin tärkeimpiin käyttäjille suunnattuihin virstanpylväisiin, jos projekti on yli kuukauden mittainen.

Käytä kalenteripäiviä, jotta voit ottaa huomioon etuyhteydettömät viivästykset, lomat, kokoukset ja niin edelleen. Sen pitäisi näyttää tältä:

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

Lisää [Update]alakohta tähän, jos joidenkin näiden virstanpylväiden arvioitu saapumisaika muuttuu, jotta sidosryhmät näkevät helposti ajantasaiset arviot.

Olemassa oleva ratkaisu

Nykyisen toteutuksen kuvaamisen lisäksi sinun tulee myös käydä läpi korkean tason esimerkkivirta havainnollistaaksesi, miten käyttäjät ovat vuorovaikutuksessa tämän järjestelmän kanssa ja / tai miten data kulkee sen läpi.

käyttäjätarinaon loistava tapa kehittää tämä. Muista, että järjestelmässäsi voi olla erityyppisiä käyttäjiä, joilla on erilaiset käyttötapaukset.

Ehdotettu ratkaisu

Jotkut ihmiset kutsuvat tätä teknisen arkkitehtuurin osaksi. Yritä jälleen käydä läpi käyttäjän tarina konkretisoidaksesi tämän. Voit vapaasti lisätä monia alaosia ja kaavioita.

Anna ensin iso kuva ja täytä sitten erät/yksityiskohdat. Tavoitteena maailma, johon voit kirjoittaa tämän, sitten lomalla jollakin autio saarella, ja toinen insinööri tiimistä voi vain lukea sen ja toteuttaa ratkaisun kuten kuvailit.

Vaihtoehtoiset ratkaisut

Mitä muuta harkitsit keksittäessäsi yllä olevaa ratkaisua? Mitkä ovat vaihtoehtojen edut ja haitat? Oletko harkinnut sellaisen kolmannen osapuolen ratkaisun ostamista - tai avoimen lähdekoodin käyttämistä -, joka ratkaisee tämän ongelman, oman rakentamisen sijaan?

Testattavuus, seuranta ja hälytys

Pidän tämän osan sisällyttämisestä, koska ihmiset pitävät tätä usein jälkikäteen tai ohittavat kaiken yhdessä, ja se palaa melkein aina puremaan heitä myöhemmin, kun asiat hajoavat, eikä heillä ole aavistustakaan miten tai miksi.

Ryhmien välinen vaikutus

Kuinka tämä lisääntyy päivystys- ja kehitystoiminnan taakassa?

Kuinka paljon rahaa se maksaa?

Aiheuttaako se järjestelmälle viiveen regressiota?

Paljastako se tietoturva-aukkoja?

Mitä negatiivisia seurauksia ja sivuvaikutuksia on?

Kuinka tukitiimi voi viestiä tästä asiakkaille?

Avoimia kysymyksiä

Kaikki avoimet kysymykset, joista et ole varma, kiistanalaiset päätökset, joihin haluat lukijoiden punnittavan, ehdotetut työt ja niin edelleen. Tämän osan kieli poskessa nimi on ”tunnetut tuntemattomat”.

Yksityiskohtainen kattavuus ja aikajana

Tämän osan lukevat enimmäkseen vain projektissa työskentelevät insinöörit, heidän tekniset johtajansa ja johtajansa. Siksi tämä osa on asiakirjan lopussa.

Pohjimmiltaan tämä on erittely siitä, miten ja milloin aiot suorittaa projektin kunkin osan. Suojauksen tarkkaan määrittelyyn menee paljon, joten voit lukea tämän viestin saadaksesi lisätietoja laajennuksesta.

Minulla on tapana käsitellä myös tätä suunnitteludokumentin osaa jatkuvana projektitehtävien seuraajana, joten päivitän tämän aina, kun laajuusarvio muuttuu. Mutta se on enemmän henkilökohtaista mieltymystä.

Kuinka kirjoittaa se

Nyt kun olemme puhuneet siitä, mistä tulee hyvä muotoiluasiakirja, puhutaan kirjoittamistyylistä. Lupaan, että tämä on erilainen kuin lukion englantiluokka.

Kirjoita mahdollisimman yksinkertaisesti

Älä yritä kirjoittaa kuten lukemasi akateemiset artikkelit. Ne on kirjoitettu vaikuttamaan lehden arvostelijoihin. Asiakirjasi on kirjoitettu kuvaamaan ratkaisusi ja saamaan palautetta joukkuetovereiltasi. Voit saavuttaa selkeyden käyttämällä:

  • Yksinkertaiset sanat
  • Lyhyet lauseet
  • Luettelomerkit ja / tai numeroidut luettelot
  • Konkreettisia esimerkkejä, kuten "Käyttäjä Alice yhdistää pankkitilisi, sitten ..."

Lisää paljon kaavioita ja kaavioita

Kaavioista voi usein olla hyötyä useiden mahdollisten vaihtoehtojen vertailussa, ja kaavioita on yleensä helpompi jäsentää kuin tekstiä. Minulla on ollut onnea Google Drawingin kanssa kaavioiden luomisessa.

Pro-vinkki: muista lisätä linkki kaavion muokattavaan versioon kuvakaappauksen alle, jotta voit helposti päivittää sen myöhemmin, kun asiat väistämättä muuttuvat.

Sisällytä numerot

Ongelman laajuus määrää usein ratkaisun. Auta arvioijia saamaan käsitys maailman tilasta sisällyttämällä reaaliluvut, kuten # DB-riviä, # käyttäjän virheiden määrä, viive - ja kuinka nämä skaalautuvat käytön kanssa. Muistatko Big-O-merkinnät?

Yritä olla hauska

Spec ei ole akateeminen paperi. Ihmiset pitävät myös hauskojen asioiden lukemisesta, joten tämä on hyvä tapa pitää lukija kiinnostuneina. Älä kuitenkaan liioittele tätä siihen saakka, että otat pois ydinideasta.

Jos sinulla, kuten minäkin, on vaikeuksia olla hauska, Joel Spolsky (joka tunnetaan ilmeisesti koomisista kykyistään…) tarjoaa tämän vinkin:

Yksi helpoimmista tavoista olla hauska on olla tarkka, kun sitä ei vaadita [… Esimerkki:] Sen sijaan, että sanoisit "erityisintressit", sano "vasenkätiset avakadonviljelijät".

Suorita skeptinen testi

Ennen kuin lähetät suunnitteludokumentin muille tarkistettavaksi, ota se läpi, kun teeskentelet olevasi arvostelija. Mitä kysymyksiä ja epäilyksiä sinulla voi olla tästä mallista? Sitten puhu heille ennakoivasti.

Tee loma-testi

Jos lähdet pitkälle lomalle nyt ilman internetyhteyttä, voiko joku tiimistäsi lukea asiakirjan ja toteuttaa sen haluamallasi tavalla?

Suunnitteludokumentin päätavoitteena ei ole tiedon jakaminen, mutta tämä on hyvä tapa arvioida selkeyden vuoksi, jotta muut voivat todella antaa sinulle hyödyllistä palautetta.

Käsitellä asiaa

Voi kyllä, pelätty P-sana . Suunnitteludokumentit auttavat sinua saamaan palautetta, ennen kuin tuhlataan joukko aikaa väärän tai väärän ongelman ratkaisuun. Hyvä palaute on paljon taidetta, mutta se on myöhempää artikkelia varten. Nyt puhutaan vain siitä, kuinka kirjoittaa suunnitteluasiakirja ja saada siitä palautetta.

Ensinnäkin kaikkien projektin parissa työskentelevien tulisi olla osa suunnitteluprosessia. Se on okei, jos tekninen johtaja päätti ajaa paljon päätöksiä, mutta kaikkien tulisi olla mukana keskustelussa ja ostaa suunnittelua. Joten "sinä" tässä artikkelissa on todella monikko "sinä", joka sisältää kaikki projektin ihmiset.

Toiseksi suunnitteluprosessi ei tarkoita sitä, että tuijottaisit ideoita teorioivaa taulua. Likaise kätesi ja prototyyppisi mahdolliset ratkaisut. Tämä ei ole sama kuin projektin tuotantokoodin kirjoittamisen aloittaminen ennen suunnitteludokumentin kirjoittamista. Älä tee niin. Mutta ehdottomasti pitäisi rohkeasti kirjoittaa joitakin hacky kertakäyttö koodin vahvistaa idean. Varmista, että kirjoitat vain kokeilukoodia, tekemällä säännön, että mitään prototyyppikoodista ei yhdistetä päälliköksi .

Sen jälkeen, kun sinulla on jonkinlainen käsitys projektin jatkamisesta, toimi seuraavasti:

  1. Pyydä kokenut insinööri tai tiimisi tekninen johtaja arvostelijaksi. Ihannetapauksessa tämä olisi joku, jota kunnioitetaan hyvin ja / tai joka tuntee ongelman reunatapaukset. Lahjoita heidät boballa tarvittaessa.
  2. Mene kokoushuoneeseen taulun kanssa.
  3. Kuvaile ongelmaa, jonka kohtaat tällä insinöörillä (tämä on erittäin tärkeä askel, älä ohita sitä!).
  4. Selitä sitten mielessäsi oleva toteutus ja vakuuttaa heille, että tämä on oikea asia rakentaa.

Kun teet kaiken tämän ennen kuin edes aloitat suunnitteludokumentin kirjoittamista, saat palautetta mahdollisimman pian, ennen kuin investoit enemmän aikaa ja kiinnität erityiseen ratkaisuun. Usein, vaikka toteutus pysyisi ennallaan, arvostelijasi pystyy osoittamaan kulmatapaukset, jotka sinun on käsiteltävä, ilmoittamaan mahdolliset sekaannukset ja ennakoimaan myöhemmin mahdollisesti kohtaamasi vaikeudet.

Kun olet kirjoittanut karkean luonnoksen suunnitteludokumentista, pyydä samaa arvostelijaa lukemaan se uudelleen ja kumileimaamalla se lisäämällä heidän nimensä arvostelijaksi suunnitteludokumentin Otsikko ja Ihmiset -osioon. Tämä luo arvioijalle lisää kannustimia ja vastuullisuutta.

Harkitse tässä yhteydessä erikoistuneiden tarkastajien (kuten SRE: t ja turvallisuusinsinöörit) lisäämistä suunnittelun tiettyihin näkökohtiin.

Kun sinä ja arvostelija (t) kirjaudutte sisään, lähetä suunnitteludokumentti tiimillesi palautetta ja tiedon jakamista varten. Ehdotan, että tämä palautteen keräämisprosessi aikarajoitetaan noin viikkoon pitkittyneiden viivästysten välttämiseksi. Sitoudu vastaamaan kaikkiin kysymyksiin ja kommentteihin, jotka ihmiset jättävät kyseisen viikon kuluessa. Kommenttien jättäminen roikkumaan = huono karma.

Lopuksi, jos sinun, arvostelijasi ja muiden asiakirjaa lukevien insinöörien välillä on paljon kiistoja, suosittelen vahvasti, että kaikki kiistakohdat yhdistetään asiakirjasi Keskustelu- osioon. Järjestä sitten kokous eri osapuolten kanssa puhuaksesi näistä erimielisyyksistä henkilökohtaisesti.

Aina kun keskustelulanka on yli 5 kommenttia pitkä, siirtyminen henkilökohtaiseen keskusteluun on yleensä paljon tehokkaampaa. Muista, että olet edelleen vastuussa viimeisen puhelun soittamisesta, vaikka kaikki eivät pääse yksimielisyyteen.

Puhuessani Shrey Bangan kanssa äskettäin tästä sain tietää, että Quipillä on samanlainen prosessi, paitsi että sen lisäksi, että tiimissäsi on kokenut insinööri tai tekninen johtaja arvostelijana, he ehdottavat myös, että toisen tiimin insinööri tarkastelee asiakirjaa. En ole kokeillut tätä, mutta näen varmasti, että tämä auttaa saamaan palautetta erilaisista näkökulmista kärsiviltä ihmisiltä ja parantamaan asiakirjan yleistä luettavuutta.

Kun olet tehnyt kaikki yllä olevat, on aika aloittaa toteutus! Lisää brownie-pisteitä käsittelemällä tätä suunnitteludokumenttia elävänä asiakirjana, kun toteutat suunnittelua . Päivitä asiakirja joka kerta, kun opit jotain, joka johtaa siihen, että teet muutoksia alkuperäiseen ratkaisuun tai päivität laajennustasi. Kiität myöhemmin, kun sinun ei tarvitse selittää asioita uudestaan ​​ja uudestaan ​​kaikille sidosryhmillesi.

Lopuksi, lähdetään todella meta toista: Miten arvioimme onnistumisen suunnittelu doc?

Työtoverillani Kent Rakipilla on tähän hyvä vastaus: Suunnitteludokumentti onnistuu, jos työn oikea ROI tehdään. Tämä tarkoittaa, että onnistunut suunnitteludokumentti voi todella johtaa tällaiseen tulokseen:

  1. Vietät 5 päivää suunnitteludokumentin kirjoittamiseen, mikä pakottaa sinut miettimään teknisen arkkitehtuurin eri osia
  2. Saat arvioijilta palautetta, joka Xon ehdotetun arkkitehtuurin riskialttiin osa
  3. Päätät ensin toteuttaa Xhankkeen riskin vähentämiseksi
  4. 3 päivää myöhemmin huomaat, että se Xei ole joko mahdollista tai paljon vaikeampaa kuin alun perin tarkoitit
  5. Päätät lopettaa työskentelyn tämän projektin kanssa ja priorisoida muut työt sen sijaan

Tämän artikkelin alussa sanoimme, että suunnitteludokumentin tavoitteena on varmistaa, että oikea työ tehdään. Yllä olevassa esimerkissä tämän suunnitteludokumentin ansiosta olet viettänyt vain 8 päivää sen sijaan, että tuhlattaisit mahdollisesti kuukausia vain projektin keskeyttämiseksi myöhemmin. Minusta näyttää melko onnistuneelta lopputulokselta.

Jätä kommentti alle, jos sinulla on kysyttävää tai palautetta! Haluaisin mielelläni kuulla myös siitä, miten suunnittelet dokumentteja tiimissäsi eri tavalla.

Antaessani luottoa siellä, missä luottoa maksetaan, olen oppinut paljon edellä mainituista työskentelemällä yhdessä uskomattomien insinöörien kanssa Plaidissa (palkkaamme! Tule suunnittelemaan ja rakentamaan hienoja teknisiä järjestelmiä kanssamme) ja Quoraan.

Jos pidät tästä viestistä, seuraa minua Twitterissä saadaksesi lisää viestejä suunnittelusta, prosesseista ja taustajärjestelmistä.