tím, že Angela Zhang
Jako softwarový inženýr, strávil jsem hodně času čtení a psaní projektové dokumentace. Poté, co jsem prošel stovkami těchto dokumentů, viděl jsem z první ruky silnou korelaci mezi dobrými designovými dokumenty a konečným úspěchem projektu.
tento článek je můj pokus o popis toho, co dělá designový dokument skvělý.,
článek je rozdělen do 4 sekcí:
- Proč psát návrh dokumentu
- Co patří do design dokumentu
- Jak to napsat
- proces kolem ní
Proč psát design dokument?
design doc – také známý jako technický spec-je popis toho, jak plánujete problém vyřešit.
existuje spousta spisů již o tom, proč je důležité napsat design doc před potápěním do kódování. Takže vše, co řeknu, je:
design doc je nejužitečnějším nástrojem pro zajištění správné práce.,
hlavním cílem design doc je zvýšit efektivitu tím, že vás nutí přemýšlet o návrhu a shromažďovat zpětnou vazbu od ostatních. Lidé si často myslí, že smyslem návrhu doc je učit ostatní o nějakém systému nebo sloužit jako dokumentace později. I když to mohou být prospěšné vedlejší účinky, nejsou cílem samy o sobě.
obecně platí, že pokud pracujete na projektu, který by mohl trvat 1 měsíc nebo déle, měli byste napsat návrhový dokument. Ale nezastavujte se tam-mnoho menších projektů by mohlo těžit z mini design doc příliš.
skvělé!, Pokud stále čtete, věříte v důležitost návrhových dokumentů. Různé inženýrské týmy a dokonce i inženýři ve stejném týmu však často píší designové dokumenty velmi odlišně. Takže pojďme mluvit o obsahu, stylu a procesu dobrého návrhu doc.
Co zahrnout do návrhu doc?
návrhový dokument popisuje řešení problému. Vzhledem k tomu, že povaha každého problému je jiná, přirozeně byste chtěli strukturovat svůj návrh doc jinak.,
začít, následující je seznam sekcí, které byste měli alespoň zvážit, včetně v dalším návrhu doc:
Nadpis
název vašeho návrhu doc, autor(s) (by měl být stejný jako seznam lidí, plánování práce na tomto projektu), recenzent(y) prohlášení o shodě (budeme mluvit o tom více v sekci Process níže), a datum tento dokument byl naposledy aktualizován.
přehled
souhrn na vysoké úrovni, který by měl každý inženýr ve společnosti pochopit a použít k rozhodnutí, zda je pro ně užitečné přečíst si zbytek doc., Mělo by to být 3 odstavce max.
kontext
popis problému, proč je tento projekt nezbytný, co lidé potřebují vědět k posouzení tohoto projektu a jak zapadá do technické strategie, produktové strategie nebo čtvrtletních cílů týmu.,
Cíle a Non-Cíle
V sekci Cíle by měly:
- popsat uživatel-řízený dopad vašeho projektu, kde by uživatel mohl být další tým techniků nebo i jiný technický systém
- určit, jak měřit úspěch pomocí metriky — bonusové body, pokud můžete připojit k palubní desce, který sleduje tyto metriky
Non-Cíle jsou stejně důležité popsat, jaké problémy vám nebude opravovat, takže každý je na stejné stránce.,
milníky
seznam měřitelných kontrolních bodů, takže váš PM a správce vašeho manažera jej mohou sbírat a zhruba vědět, kdy budou provedeny různé části projektu. Doporučuji vám rozdělit Projekt na hlavní milníky orientované na uživatele,pokud je projekt delší než 1 měsíc.
použijte kalendářní data, abyste vzali v úvahu nesouvisející zpoždění, dovolenou, schůzky atd., Mělo by to vypadat nějak takhle:
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
Přidat podsekce pokud ETA některé z těchto milník změny, takže zainteresované strany mohou snadno zjistit, nejvíce up-to-date odhady.
Stávající Řešení
kromě popisu současného provádění, byste měli také projít vysokou úroveň příklad toku pro ilustraci, jak uživatelé komunikovat s tímto systémem a/nebo, jak data protékají.,
příběh uživatele je skvělý způsob, jak to zarámovat. Mějte na paměti, že váš systém může mít různé typy uživatelů s různými případy použití.
navrhované řešení
někteří lidé nazývají tuto sekci technické architektury. Znovu se pokuste projít uživatelským příběhem, abyste to konkretizovali. Neváhejte zahrnout mnoho dílčích částí a diagramů.
nejprve uveďte velký obrázek a poté vyplňte spoustu podrobností. Zaměřte se na svět, kde to můžete napsat, pak si vezměte dovolenou na nějakém opuštěném ostrově a další inženýr v týmu si to může přečíst a implementovat řešení, jak jste popsali.,
alternativní řešení
Co jiného jste zvažovali, když jste přišli s výše uvedeným řešením? Jaké jsou výhody a nevýhody alternativ? Uvažovali jste o koupi řešení 3rd-party-nebo pomocí open source jeden-který řeší tento problém na rozdíl od budování své vlastní?
Testovatelnost, Monitorování a Výstrahy
mám rád včetně této sekci, protože lidé často léčit to jako nápad nebo přeskočit to všechno dohromady, a to téměř vždy vrací, aby je později, když se věci pauzu a nemají tušení, jak nebo proč.,
Cross-Team Impact
Jak se toto zvýší na call a Dev-ops zátěž?
kolik peněz to bude stát?
způsobuje nějakou regresi latence do systému?
vystavuje nějaké bezpečnostní chyby?
jaké jsou některé negativní důsledky a vedlejší účinky?
Jak to může tým podpory sdělit zákazníkům?
otevřené otázky
jakékoli otevřené problémy, o kterých si nejste jisti, sporná rozhodnutí, která byste chtěli, aby čtenáři zvážili, navrhli budoucí práci atd. Název jazyka v tváři pro tuto sekci je „známé neznámé“.,
Detailní stanovení Rozsahu a časové Osy
Tento oddíl je většinou bude číst pouze inženýři, kteří pracují na tomto projektu, jejich tech vede, a jejich manažeři. Proto je tato část na konci dokumentu.
v podstatě se jedná o rozpis toho, jak a kdy plánujete provedení každé části projektu. Je toho hodně, co jde přesně do scopingu, takže si můžete přečíst tento příspěvek a dozvědět se více o scopingu.
mám tendenci také tuto sekci Design doc považovat za průběžný sledovač úloh projektu, takže to aktualizuji vždy, když se změní můj odhad., Ale to je spíš osobní preference.
Jak to napsat
Teď, když jsme mluvili o tom, co se děje v dobrý design doktore, pojďme mluvit o stylu psaní. Slibuju, že je to jiné, než tvoje středoškolská angličtina.
napište co nejjednodušší
nepokoušejte se psát jako akademické práce, které jste četli. Jsou napsány, aby zapůsobily na recenzenty časopisů. Váš dokument je napsán, aby popsal vaše řešení a získal zpětnou vazbu od vašich spoluhráčů., Můžete dosáhnout jasnosti pomocí:
- Jednoduchá slova
- Krátké věty
- seznamy s Odrážkami a/nebo číslovaných seznamů
- Konkrétní příklady, jako „Uživatel Alice připojí svůj bankovní účet, pak …“
Přidat spoustu grafů a schémat
Grafy mohou být často užitečné porovnat několik potenciálních možností, a schémata jsou obecně jednodušší zpracovat, než text. Měl jsem hodně štěstí s kresbou Google pro vytváření diagramů.,
Pro Tip: nezapomeňte přidat odkaz na editovatelné verzi diagramu podle obrázku, takže můžete snadno aktualizovat později, když se věci nevyhnutelně změnit.
zahrnují čísla
měřítko problému často určuje řešení. Chcete — li pomoci recenzentům získat pocit stavu světa, zahrnout reálná čísla jako # řádků DB, # uživatelských chyb, latence-a jak tyto měřítko s použitím. Vzpomínáš si na své velké notace?
zkuste být vtipný
spec není akademický dokument. Také lidé rádi čtou vtipné věci, takže je to dobrý způsob, jak udržet čtenáře v záběru., Nepřehánějte to do té míry, že se zbavíte základní myšlenky.
Pokud jste, stejně jako já, mají problémy se být vtipný, Joel Spolsky (samozřejmě známý pro jeho komediální talent…) má tento tip:
Jeden z nejjednodušších způsobů, jak být vtipný, má být konkrétní, když to není nutné, Místo toho říkat „zvláštní zájmy“, říká, „levou rukou avacado zemědělců.“
Skeptik Test
Před odesláním návrhu doc na ostatní recenze, se projít na to předstírá, že recenzent. Jaké otázky a pochybnosti můžete mít o tomto designu?, Pak je oslovte preventivně.
Udělat Dovolenou Test
Pokud jste jít na dlouhou dovolenou bez přístupu k internetu, může někdo z vašeho týmu číst doc a realizovat to, jak jste zamýšleli?
hlavním cílem design doc není sdílení znalostí, ale je to dobrý způsob, jak vyhodnotit jasnost, aby vám ostatní mohli skutečně poskytnout užitečnou zpětnou vazbu.
ano, obávaný P-slovo., Konstrukční dokumenty vám pomohou získat zpětnou vazbu, než ztratíte spoustu času implementací nesprávného řešení nebo řešení špatného problému. Je tu spousta umění Získat dobrou zpětnou vazbu, ale to je pro pozdější článek. Prozatím hovoříme konkrétně o tom, jak napsat návrh doc a získat zpětnou vazbu.
nejprve by měl být součástí procesu návrhu každý, kdo pracuje na projektu. Je to v pořádku, pokud tech olovo skončí řídit spoustu rozhodnutí, ale každý by měl být zapojen do diskuse a koupit do návrhu., Takže „vy“ v tomto článku je opravdu množné číslo „vy“, které zahrnuje všechny lidi na projektu.
Zadruhé, proces návrhu neznamená, že zíráte na myšlenky teoretizující tabuli. Nebojte se zašpinit ruce a prototypovat potenciální řešení. To není totéž, jako začít psát výrobní kód projektu před napsáním návrhu doc. Nedělej to. Ale rozhodně byste měli bez obav napsat nějaký hacky throwaway kód k ověření nápadu., Chcete-li zajistit, že budete psát pouze průzkumný kód, aby bylo pravidlem, že žádný z tohoto prototypu kódu dostane sloučeny zvládnout.
Po tom, jak se začnete mít nějakou představu o tom, jak jít o vašem projektu, proveďte následující kroky:
- Zeptejte se zkušeného inženýra nebo tech vedou na váš tým, aby se vaše recenzent. V ideálním případě by to byl někdo, kdo je dobře respektován a / nebo obeznámen s okrajovými případy problému. Podplatit je boba v případě potřeby.
- jděte do konferenční místnosti s tabulí.,
- popište problém, který řešíte tomuto inženýrovi (jedná se o velmi důležitý krok, nevynechávejte jej!).
- pak vysvětlete implementaci, kterou máte na mysli, a přesvědčte je, že je to správná věc.
to vše předtím, než začnete psát svůj design doc, vám umožní získat zpětnou vazbu co nejdříve, než investujete více času a připojíte se k jakémukoli konkrétnímu řešení., Často, i když implementace zůstane stejná, váš Recenzent je schopen poukázat na rohové případy, které musíte pokrýt, uvést případné oblasti zmatku a předvídat potíže, se kterými se můžete později setkat.
poté, co jste napsali hrubý náčrt vašeho návrhu doc, dostat stejné recenzent přečtěte si to znovu, a razítko je tím, že přidá své jméno jako recenzent v Názvu a Lidé části návrhu doc. To vytváří další pobídku a odpovědnost pro recenzenta.,
v této poznámce zvažte přidání specializovaných recenzentů (jako jsou SREs a bezpečnostní inženýři) pro konkrétní aspekty návrhu.
Jakmile jste a recenzenta(s) podepsat, neváhejte a pošlete návrh doc do svého týmu pro další zpětnou vazbu a sdílení znalostí. Navrhuji časově ohraničující tento proces shromažďování zpětné vazby na přibližně 1 týden, aby se zabránilo prodlouženým zpožděním. Zavázat se k řešení všech otázek a komentářů, které lidé opustí během tohoto týdne. Zanechání komentářů = špatná karma . ,
a Konečně, pokud tam je hodně sváru mezi vámi, váš recenzent, a další inženýři čtení doktore, jsem důrazně doporučujeme upevnit všechny body sváru v Diskusní sekci dle svého doc. Poté uspořádejte schůzku s různými stranami, abyste o těchto neshodách hovořili osobně.
kdykoli je diskusní vlákno delší než 5 komentářů, přechod na osobní diskusi bývá mnohem efektivnější. Mějte na paměti, že jste stále zodpovědní za konečné volání, i když každý nemůže dospět ke konsensu.,
V rozhovoru s Shrey Banga v poslední době o tom, dozvěděl jsem se, že Vtip má podobný proces, kromě toho, že zkušený inženýr nebo tech vést svůj tým jako recenzent, oni také naznačují, že inženýr na jiný tým recenzi doc. Nezkoušel jsem to, ale určitě to vidím, jak to pomáhá získat zpětnou vazbu od lidí s různými perspektivami a zlepšit obecnou čitelnost doc.
Jakmile provedete všechny výše uvedené, je čas pokračovat v implementaci!, U dalších bodů brownie považujte tento design doc za živý dokument, když implementujete design. Aktualizace doc pokaždé, když se naučíte něco, co vede k provádění změn původního řešení, nebo aktualizovat své oborů. Poděkujete mi později, když nemusíte vysvětlovat věci znovu a znovu všem svým zúčastněným stranám.
konečně, pojďme opravdu meta na vteřinu: jak hodnotíme úspěch design doc?
můj spolupracovník Kent Rakip má dobrou odpověď na toto: design doc je úspěšný,pokud je provedena správná návratnost investic.,ts technické architektury
X je nejrizikovější část navržené architekturyX první de-rizika projektuX je to buď není možné, nebo daleko obtížnější, než jste původně zamýšleliNa začátku tohoto článku jsme si řekli, že cílem návrhu doc je, aby ujistěte se, že správné práci dostane hotovo., Ve výše uvedeném příkladu, díky tomuto návrhu doc, namísto plýtvání potenciálně měsíců pouze k přerušení tohoto projektu později, jste strávili pouze 8 dní. Zdá se mi to jako docela úspěšný výsledek.
prosím, zanechte komentář níže, pokud máte nějaké dotazy nebo zpětnou vazbu! Také bych rád slyšel o tom, jak ve svém týmu navrhujete dokumenty jinak.
poskytování kreditu, kde je splatný kredit, jsem se naučil hodně z výše uvedených tím, že pracuje po boku některých neuvěřitelných inženýrů na Plaid(najímáme! PřijĎte navrhnout a postavit nějaké sladké technické systémy s námi) a Quora.,
Pokud se vám tento příspěvek líbí, Následujte mě na Twitteru pro další příspěvky v systémech inženýrství, procesů a backendů.