Angela Zhang
szoftvermérnökként sok időt töltök tervezési dokumentumok olvasásával és írásával. Miután több száz ilyen dokumentumon mentem keresztül, első kézből láttam egy erős összefüggést a jó tervezési dokumentumok és a projekt végső sikere között.
Ez a cikk az a kísérletem, hogy leírjam, mi teszi a tervezési dokumentumot nagyszerűvé.,
a cikk 4 részre oszlik:
- miért írjon egy tervezési dokumentumot
- mit kell tartalmaznia egy tervezési dokumentumban
- hogyan kell írni
- a körülötte lévő folyamat
miért írjon egy tervezési dokumentumot?
a tervezési doc-más néven műszaki specifikáció-annak leírása, hogyan tervezi megoldani a problémát.
már sok írás van arról, hogy miért fontos tervezési doc írása, mielőtt a kódolásba merülne. Tehát itt csak annyit mondok:
a tervezési doc a leghasznosabb eszköz annak biztosítására, hogy a megfelelő munka megtörténjen.,
a design doc fő célja, hogy hatékonyabbá tegye Önt azáltal, hogy arra kényszeríti Önt, hogy átgondolja a tervezést, és visszajelzést gyűjtsön másoktól. Az emberek gyakran úgy gondolják, hogy a tervezési dokumentum lényege, hogy másokat tanítson valamilyen rendszerről, vagy később dokumentációként szolgáljon. Bár ezek jótékony mellékhatások lehetnek, nem maguk a cél.
általános hüvelykujjszabályként, ha olyan projekten dolgozik, amely 1 mérnök-hónapot vagy annál többet igényelhet, írjon egy tervezési dokumentumot. De ne állj meg ott — sok kisebb projekt részesülhet egy mini design doc-ból is.
nagyszerű!, Ha még mindig olvas, hisz a tervezési dokumentumok fontosságában. Azonban a különböző mérnöki csapatok, sőt ugyanazon csapat mérnökei gyakran nagyon eltérő módon írják a tervezési dokumentumokat. Tehát beszéljünk a tartalom, stílus, folyamat egy jó design doc.
mit kell belefoglalni egy tervezési dokumentumba?
a tervezési doc leírja a probléma megoldását. Mivel a természet minden probléma más, természetesen azt szeretné, hogy a design doc másképp.,
A start, a következő egy lista a szakaszok, amelyek legalább fontolja meg, ideértve a következő tervezési doki:
Cím Emberek
A címet a design doki, a szerző(k) (meg kell egyeznie a listája, akik tervezi, hogy dolgozik ezen a projekten), a bíráló(k) a doki (majd beszélünk még róla, hogy a Folyamat szakaszt), a dátum, ez a dokumentum volt utoljára frissítve.
áttekintés
magas szintű összefoglaló, amelyet a vállalat minden mérnökének meg kell értenie és használnia kell annak eldöntéséhez, hogy hasznos-e számukra a doc többi részének elolvasása., Meg kell 3 bekezdés max.
kontextus
a probléma leírása, miért van szükség erre a projektre, mit kell tudniuk az embereknek a projekt értékeléséhez, valamint hogyan illeszkedik a technikai stratégiába, termékstratégiába vagy a csapat negyedéves céljaiba.,
Célok, mind a Nem-Célok
A Célok részben kell:
- leírni a felhasználó-vezérelt hatása a projekt—, ahol a felhasználó egy másik mérnöki csoport, vagy akár egy másik technikai rendszer
- megadja, hogy az intézkedés sikere a mutatók — bónusz pontokat, ha tudsz linket a műszerfal, amely nyomon követi a mutatókat
a Nem-Célok egyaránt fontos, hogy leírja, hogy mely problémákat nem lehet megjavítani, így mindenki ugyanazon az oldalon.,
mérföldkövek
a mérhető ellenőrző pontok listája, így a PM és a menedzser menedzserének nagyjából meg lehet tudni, hogy mikor történik meg a projekt különböző részei. Azt javasoljuk, hogy megtörje a projekt le a nagy felhasználó-néző mérföldkövek, ha a projekt több mint 1 hónap hosszú.
használja a naptári dátumokat, így figyelembe veszi a nem kapcsolódó késéseket, vakációkat, találkozókat stb., Így kell kinéznie:
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
alszakasz itt, ha néhány ilyen mérföldkő eta megváltozik, így az érdekeltek könnyen láthatják a legfrissebb becsléseket.
meglévő megoldás
az aktuális implementáció leírásán túl magas szintű példaáramlást kell végigjárnia annak illusztrálására, hogy a felhasználók hogyan lépnek kapcsolatba ezzel a rendszerrel és/vagy hogyan áramlik át rajta az adatok.,
a felhasználói történet nagyszerű módja ennek keretezésére. Ne feledje, hogy a rendszer különböző típusú felhasználókkal rendelkezhet, különböző használati esetekkel.
javasolt megoldás
egyesek ezt a műszaki architektúra szakasznak nevezik. Ismét próbáljon végigmenni egy felhasználói történeten, hogy konkretizálja ezt. Nyugodtan, hogy számos al-szakaszok, diagramok.
először adjon meg egy nagy képet, majd töltsön be sok részletet. Cél egy olyan világban, ahol lehet írni ezt, majd egy nyaralás néhány lakatlan szigeten, és egy másik mérnök a csapat csak olvasni, és végre a megoldást, mint leírta.,
alternatív megoldások
mit gondolt még a fenti megoldás kidolgozásakor? Melyek az alternatívák előnyei és hátrányai? Gondoltál már egy 3rd-party megoldás megvásárlására — vagy egy nyílt forráskódú megoldásra -, amely megoldja ezt a problémát, szemben a saját építésével?
Tesztelhetőség, monitorozás és riasztás
szeretem ezt a részt, mert az emberek gyakran ezt utólag kezelik, vagy együtt kihagyják, és szinte mindig visszajön, hogy később megharapja őket, amikor a dolgok megszakadnak, és fogalmuk sincs, hogyan vagy miért.,
Cross-Team Impact
hogyan fog ez növekedni a call-and dev-ops teher?
mennyibe fog kerülni?
okoz-e késleltetési regressziót a rendszerben?
kiteszi-e a biztonsági réseket?
mik azok a negatív következmények és mellékhatások?
Hogyan kommunikálhatja ezt a támogató csapat az ügyfelekkel?
nyitott kérdések
minden olyan nyitott kérdés, amelyben nem biztos, vitatott döntések, amelyeket az olvasók mérlegelni szeretnének, javasolt jövőbeli munka stb. Ennek a szakasznak a nyelv-in-cheek neve az “ismert ismeretlen”.,
részletes leírás és idővonal
ezt a részt többnyire csak a projekten dolgozó mérnökök, műszaki vezetőik és menedzsereik fogják elolvasni. Ezért ez a szakasz a doc végén van.
lényegében ez a bontás, hogy hogyan és mikor tervezi a projekt egyes részeinek végrehajtását. Van egy csomó, hogy megy a scoping pontosan, így elolvashatja ezt a bejegyzést, hogy többet megtudni scoping.
a tervezési dokumentum ezen szakaszát is folyamatban lévő projektfeladat-Nyomkövetőként kezelem, ezért frissítem ezt, amikor a felmérési becslésem megváltozik., De ez inkább személyes preferencia.
hogyan kell írni
most, hogy beszéltünk arról, hogy mi megy egy jó design doc-ba, beszéljünk az írás stílusáról. Ígérem, ez más, mint a középiskolai angol órád.
írjon a lehető legegyszerűbben
ne próbáljon úgy írni, mint az olvasott tudományos papírok. Ők írták, hogy lenyűgözni folyóirat bírálók. A dokit azért írták, hogy leírja a megoldást, és visszajelzést kapjon a csapattársaitól., Az egyértelműséget a következők segítségével érheti el:
- egyszerű szavak
- rövid mondatok
- felsorolt listák és/vagy számozott listák
- konkrét példák, mint például: “a felhasználó Alice összeköti a bankszámláját, akkor …”
adjon hozzá sok diagramot és diagramot
a diagramok gyakran hasznosak lehetnek több lehetséges opció összehasonlításához, és a diagramok általában könnyebben értelmezhetők, mint a szöveg. Sok szerencsém volt a Google rajzával diagramok készítéséhez.,
Pro tipp: ne felejtsen el hozzáadni egy linket a diagram szerkeszthető verziójához a képernyőkép alatt, így később könnyen frissítheti, amikor a dolgok elkerülhetetlenül megváltoznak.
tartalmazza a számokat
a probléma skálája gyakran meghatározza a megoldást. Segíteni a kritikusok egy értelemben, hogy az állam a világon, magában foglalja a számok, mint a # a DB sor, # a felhasználói hibák, latency — hogy ezek a skála használata. Emlékszel a nagy-O jelöléseidre?
próbálj meg vicces lenni
a spec nem akadémiai papír. Is, az emberek szeretnek olvasni vicces dolgokat, így ez egy jó módja annak, hogy az olvasó részt., Ne vigyük túlzásba, hogy a lényeg, hogy elvegye a mag ötlet mégis.
Ha Ön, mint én, nehezen vicces, Joel Spolsky (nyilvánvalóan komikus tehetségeiről ismert…) rendelkezik ezzel a tippel:
az egyik legegyszerűbb módja annak, hogy viccesnek lehessen lenni, ha nem hívják fel a “különleges érdekek” helyett, mondjuk ” Balkezes avacado gazdák.”
végezze el a szkeptikus tesztet
mielőtt elküldené a tervezési dokumentumot másoknak, hogy áttekintsék, vegyen át rajta úgy, mintha a recenzens lenne. Milyen kérdései és kétségei lehetnek ezzel a dizájnnal kapcsolatban?, Ezután előzetesen foglalkozzon velük.
végezze el a vakációs tesztet
ha hosszú vakációra megy most internet-hozzáférés nélkül, elolvashatja-e valaki a csapatából a doc-t, és végrehajthatja azt a kívánt módon?
a tervezési dokumentum fő célja nem a tudásmegosztás, de ez egy jó módszer az egyértelműség értékelésére, hogy mások valóban hasznos visszajelzést adhassanak.
folyamat
ah igen, a rettegett p-szó., A tervezési dokumentumok segítenek visszajelzést kapni, mielőtt egy csomó időt pazarolna a rossz megoldás vagy a rossz probléma megoldására. Van egy csomó művészeti szerzés jó visszajelzést, de ez egy későbbi cikk. Egyelőre csak beszéljünk konkrétan arról, hogyan írjuk meg a tervezési dokumentumot, és kapjunk visszajelzést.
mindenekelőtt mindenkinek, aki a projekten dolgozik, a tervezési folyamat részét kell képeznie. Nem baj, ha a technikai vezető végül vezetés sok a döntéseket, de mindenkinek be kell vonni a vita, és vásárolni a design., Tehát a” te “ebben a cikkben egy igazán többes számú “te”, amely magában foglalja a projekt összes emberét.
másodszor, a tervezési folyamat nem jelenti azt, hogy bámulja a tábla elméleti ötleteit. Ne habozzon, hogy a kezét piszkos, prototípus lehetséges megoldásokat. Ez nem ugyanaz, mint a tervezési doc írása előtt a projekt gyártási kódjának megírása. Ne csináld ezt. De feltétlenül szabadnak kell lennie, hogy írjon néhány hacky eldobható kódot az ötlet érvényesítéséhez., Annak érdekében, hogy csak írni feltáró kódot, hogy ez a szabály, hogy egyik sem ez a prototípus kód lesz összeolvadt mester.
ezután, amikor elkezdesz néhány ötletet a projektedről, tegye a következőket:
- kérje meg egy tapasztalt mérnököt vagy technikai vezetőt a csapatánál, hogy legyen a recenzens. Ideális esetben ez olyan személy lenne, aki tiszteletben tartja és/vagy ismeri a probléma peremes eseteit. Megvesztegetni őket boba, ha szükséges.
- menj be egy konferenciaterembe egy táblával.,
- írja le azt a problémát, amellyel ezt a mérnököt kezeli (ez egy nagyon fontos lépés, ne hagyja ki!).
- majd magyarázza el a megvalósítás van szem előtt, és meggyőzni őket, hogy ez a helyes dolog, hogy építsenek.
mindezt még mielőtt elkezdené írni a tervezési doc lehetővé teszi, hogy visszajelzést kap a lehető leghamarabb, mielőtt befektetni több időt, és kap csatolt bármely konkrét megoldás., Gyakran, még akkor is, ha a végrehajtás ugyanaz marad, a recenzens képes rámutatni sarok esetekben meg kell fedezni, jelezze a lehetséges területek zavart, és előre nehézségek esetleg találkozik később.
ezután, miután megírta a tervezési dokumentum durva tervezetét, ugyanazt a felülvizsgálót kapja meg, hogy újra elolvassa, és gumibélyegezze, ha a nevét a recenzensként adja hozzá a design doc címéhez és az emberek részéhez. Ez további ösztönzést és elszámoltathatóságot teremt a bíráló számára.,
Ezen a megjegyzésen fontolja meg a speciális felülvizsgálók (például az SREs és a biztonsági mérnökök) hozzáadását a tervezés bizonyos aspektusaihoz.
miután Ön és a recenzens(k) kijelentkeztek, nyugodtan küldjék el a design doc-t csapatának további visszajelzésekért és tudásmegosztásért. Azt javaslom, hogy ezt a visszacsatolási gyűjtési folyamatot körülbelül 1 hétre korlátozzuk a hosszabb késések elkerülése érdekében. Vállalják, hogy minden kérdésre és észrevételt az emberek elhagyják azon a héten. Megjegyzések lógása = rossz karma.,
végül, ha van egy csomó vita közted, a recenzens, és más mérnökök olvasni a doc, azt javasoljuk, hogy megszilárdítsa az összes pontot a vita a vita részben a doc. Ezután hozzon létre egy találkozót a különböző felekkel, hogy személyesen beszéljen ezekről a nézeteltérésekről.
amikor egy beszélgetési téma több mint 5 megjegyzés hosszú, a személyes beszélgetésre való áttérés sokkal hatékonyabb. Ne feledje, hogy továbbra is felelős a végső hívás kezdeményezéséért, még akkor is, ha mindenki nem tud konszenzusra jutni.,
A Shrey Banga-val való beszélgetés során a közelmúltban megtudtam, hogy a Quip hasonló folyamattal rendelkezik, kivéve, ha tapasztalt mérnök vagy technikai vezető van a csapatodban, mint véleményező, azt is javasolják, hogy egy másik csapat mérnöke vizsgálja felül a doc-t. Még nem próbáltam ezt, de biztosan látom, hogy ez segít visszajelzést kapni a különböző nézőpontú emberektől, valamint javítani a doc általános olvashatóságát.
miután elvégezte a fentieket, ideje elkezdeni a végrehajtást!, További brownie pontokért kezelje ezt a tervezési dokumentumot élő dokumentumként, amikor végrehajtja a tervezést. Frissítse a doc-t minden alkalommal, amikor megtanul valamit, ami az eredeti megoldás módosításához vagy a scoping frissítéséhez vezet. Majd később megköszönöd, ha nem kell újra és újra elmagyaráznod a dolgokat az összes érdekelt félnek.
végül, nézzük igazán meta egy pillanatra: hogyan értékeljük a sikeres tervezési doc?
munkatársam, Kent Rakip jó választ ad erre: a tervezési doc sikeres, ha a munka megfelelő ROI-ja megtörténik.,ts a műszaki architektúra
X a legkockázatosabb része a javasolt architektúraX első, de a kockázat a projektX vagy nem lehet, vagy sokkal nehezebb, mint az eredetileg tervezettaz elején ez a cikk, akkor azt mondta, a cél egy design doki, hogy győződjön meg arról, hogy a munka el legyen végezve., A fenti példában, ennek a tervezési dokumentumnak köszönhetően, ahelyett, hogy potenciálisan hónapokat pazarolna csak a projekt későbbi leállítására, csak 8 napot töltött. Nekem elég sikeres eredménynek tűnik.
kérjük, hagyjon megjegyzést alább, ha bármilyen kérdése vagy visszajelzése van! Azt is szeretném hallani, hogy hogyan tervezed a dokumentumokat másképp a csapatodban.
hitelnyújtás, ahol a hitel esedékes, sokat tanultam a fentiekből azáltal, hogy néhány hihetetlen mérnök mellett dolgoztam a Plaidnél (felveszünk! Gyere, tervezz és építs velünk néhány édes technikai rendszert) és Quora.,
Ha tetszik ez a bejegyzés, Kövess a Twitteren további bejegyzések mérnöki, folyamatok, backend rendszerek.