Szoftvermérnökként sok időt töltök tervdokumentumok olvasásával és írásával. Miután több száz ilyen dokumentumot átéltem, első kézből tapasztaltam, hogy szoros összefüggés van a jó tervdokumentumok és a projekt végső sikere között.
Ez a cikk az a kísérletem, hogy leírjam, mitől lesz nagy a tervdokumentum .
A cikk 4 részre oszlik:
- Miért kell tervdokumentumot írni
- Mit kell beépíteni a tervdokumentumba
- Hogyan kell megírni
- A körülötte zajló folyamat
Miért kell tervdokumentumot írni?
A tervdokumentum - más néven műszaki specifikáció - leírja, hogyan tervezi megoldani a problémát.
Rengeteg írás van arról, hogy miért fontos egy tervdokumentumot megírni, mielőtt belemerülnénk a kódolásba. Tehát itt csak annyit mondok:
A tervdokumentum a leghasznosabb eszköz a megfelelő munka elvégzéséhez.
A tervdokumentum fő célja az, hogy hatékonyabbá tegye Önt azzal, hogy arra kényszeríti Önt, hogy gondolja át a tervet, és gyűjtsön visszajelzéseket másoktól. Az emberek gyakran azt gondolják, hogy a tervdokumentum lényege, hogy másokat megtanítson valamilyen rendszerről, vagy később dokumentációként szolgáljon. Bár ezek előnyös mellékhatások lehetnek, önmagukban nem ez a cél.
Általános szabály, hogy ha olyan projekten dolgozik, amely 1 vagy több mérnökhónapot vehet igénybe, akkor írjon egy tervezési dokumentumot. De ne álljon meg itt - sok kisebb projekt is profitálhat egy mini design dokiból.
Nagy! Ha még mindig olvas, akkor hisz a tervdokumentumok fontosságában. Azonban a különböző mérnöki csapatok, sőt ugyanazon a csapaton belüli mérnökök is gyakran nagyon eltérő módon írják a tervezési dokumentumokat. Tehát beszéljünk egy jó tervdokumentum tartalmáról, stílusáról és folyamatáról.
Mit kell beépíteni egy tervdokumentumba?
A tervdokumentum leírja a probléma megoldását. Mivel az egyes problémák jellege más, természetesen érdemes másként felépíteni a tervdokumentumot.
Először az alábbiakban felsoroljuk azokat a szakaszokat, amelyeket legalább figyelembe kell venniebeleértve a következő tervdokumentumba:
Cím és emberek
A tervdokumentum címe, aszerző (k) (meg kell egyeznie a projekten dolgozni szándékozók listájával), a bíráló (k)(erről az alábbiakban a Folyamat szakaszban beszélünk), és a dokumentum legutóbbi frissítésének dátumáról.
Áttekintés
Magas szintű összefoglaló, amelyet a vállalat minden mérnökének meg kell értenie, és el kell döntenie, hogy hasznos-e számukra a többi dokumentum elolvasása. Legfeljebb 3 bekezdés legyen.
Kontextus
A szóban forgó probléma leírása, miért szükséges ez a projekt, mit kell tudni az embereknek a projekt értékeléséhez, és hogyan illeszkedik a technikai stratégiába, a termékstratégiába vagy a csapat negyedéves céljaiba.
Célok és nem célok
A Célok szakasznak:
- írja le a projekt felhasználó által vezérelt hatását - ahol a felhasználó egy másik mérnöki csapat vagy akár egy másik műszaki rendszer lehet
- adja meg, hogyan mérje a sikert a mutatók segítségével - bónuszpontok, ha hivatkozni tud egy irányítópultra, amely nyomon követi ezeket a mutatókat
A nem célok ugyanolyan fontosak annak leírására, hogy mely problémákat nem fogja megoldani, így mindenki ugyanazon az oldalon tartózkodik.
Mérföldkövek
Mérhető ellenőrzési pontok listája, így a PM-je és a menedzsere menedzsere átlapozhatja azt, és nagyjából tudja, hogy a projekt különböző részei mikor készülnek el. Arra ösztönzem Önt, hogy bontsa le a projektet a felhasználó számára fontos mérföldkövekre, ha a projekt hosszabb, mint 1 hónap.
Használja a naptári dátumokat, hogy figyelembe vegye a nem kapcsolódó késéseket, vakációkat, megbeszéléseket stb. Valahogy így kell kinéznie:
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
Adjon hozzá egy [Update]alszakaszt, ha e mérföldkövek némelyikének várható időtartama megváltozik, így az érdekelt felek könnyen láthatják a legfrissebb becsléseket.
Meglévő megoldás
A jelenlegi megvalósítás leírása mellett egy magas szintű példamenetet is át kell járnia annak bemutatására, hogy a felhasználók hogyan lépnek kapcsolatba ezzel a rendszerrel és / vagy hogyan áramlanak rajta keresztül az adatok.
Egy felhasználósztorinagyszerű módja ennek a keretnek. Ne feledje, hogy a rendszerének különböző felhasználói típusai lehetnek, különböző használati esetekkel.
Javasolt megoldás
Vannak, akik ezt Műszaki architektúra résznek hívják . Ismét próbáljon meg végigjárni egy felhasználói történetet ennek konkretizálásához. Nyugodtan adjon meg sok alszakaszt és ábrát.
Először adjon nagy képet, majd töltsön ki tételeketnak,-nekrészletek. Célozzon egy olyan világra, ahol ezt megírhatja, majd nyaralhat egy elhagyatott szigeten, és a csapat másik mérnöke csak elolvassa és megvalósíthatja a megoldást, ahogy leírtad.
Alternatív megoldások
Mi mást vett figyelembe, amikor a fenti megoldással állt elő? Mik az előnyei és hátrányai az alternatíváknak? Fontolgatta-e egy harmadik féltől származó megoldás megvásárlását - vagy egy nyílt forráskódú megoldást -, amely megoldja ezt a problémát, szemben a saját fejlesztésével?
Tesztelhetőség, figyelés és riasztás
Szeretem bekapcsolni ezt a szakaszt, mert az emberek gyakran ezt utólagos gondolkodásként kezelik, vagy átugorják az egészet, és szinte mindig visszatér, hogy később megharapják őket, amikor a dolgok elszakadnak, és fogalmuk sincs, hogyan és miért.
Csapatközi hatás
Hogyan növekszik ez az ügyeleti és fejlesztési terheknél?
Mennyibe kerül?
Okoz-e valamilyen késleltetési regressziót a rendszer számára?
Fed fel biztonsági réseket?
Milyen negatív következmények és mellékhatások vannak?
Hogyan tudná ezt az ügyfélszolgálat közölni az ügyfelekkel?
Nyitott kérdések
Bármely nyitott kérdés, amelyben nem biztos, vitás döntések, amelyeken mérlegelni szeretné az olvasókat, jövőbeni munkákra tett javaslatot stb. Ennek a szakasznak a nyelvről-arcra keresztneve az „ismert ismeretlen”.
Részletes hatókör és idővonal
Ezt a részt leginkább csak a projekten dolgozó mérnökök, műszaki vezetőik és menedzsereik fogják elolvasni. Ezért ez a szakasz a dok. Végén található.
Lényegében ez a lebontás arról, hogyan és mikor tervezi végrehajtani a projekt egyes részeit. Nagyon sok minden belefér a hatókör pontos meghatározásába, ezért elolvashatja ezt a bejegyzést, hogy többet megtudjon a hatókörről.
Hajlamos vagyok a tervezési dokumentum ezen szakaszát is folyamatban lévő projektfeladat-követőként kezelni, ezért frissítem ezt, amikor a hatókör-becslésem megváltozik. De ez inkább személyes preferencia.
Hogyan kell megírni
Most, hogy megbeszéltük, mi megy bele egy jó tervdokumentumba, beszéljünk az írás stílusáról. Ígérem, ez más, mint a középiskolai angol osztály.
Írjon a lehető legegyszerűbben
Ne próbáljon úgy írni, mint az elolvasott tudományos dolgozatok. Azért íródtak, hogy lenyűgözzék a folyóirat bírálóit. A dokumentumot azért írják, hogy leírja a megoldást, és visszajelzést kapjon csapattársaitól. Világosságot érhet el a következők használatával:
- Egyszerű szavak
- Rövid mondatok
- Felsorolással ellátott listák és / vagy számozott listák
- Konkrét példák, például: „Alice felhasználó összeköti a bankszámláját, majd…”
Adjon hozzá sok diagramot és diagramot
A diagramok gyakran hasznosak lehetnek több lehetséges lehetőség összehasonlításához, és az ábrákat általában könnyebb elemezni, mint a szöveget. Sok szerencsém volt a Google Rajzhoz diagramok készítéséhez.
Pro tipp: ne felejtsen el linket adni a diagram szerkeszthető verziójához a képernyőkép alatt, így később könnyedén frissítheti, amikor a dolgok elkerülhetetlenül megváltoznak.
Tartalmazza a számokat
A probléma nagysága gyakran meghatározza a megoldást. Annak érdekében, hogy az ellenőrök megértsék a világ állapotát, adjon meg valós számokat, például a DB sorok számát, a felhasználói hibák számát, a várakozási időt - és hogy ezek hogyan skálázódnak a használattal. Emlékszel a Big-O jelöléseire?
Próbálj vicces lenni
A specifikáció nem tudományos cikk. Emellett az emberek szeretnek vicces dolgokat olvasni, így ez jó módszer az olvasó elkötelezettségének fenntartására. Ezt azonban ne vigyük túlzásba úgy, hogy elvesszük az alapötletet.
Ha neked, például hozzám hasonlóan, nehézséged van viccesnek lenni, Joel Spolsky-nak ( nyilvánvalóan komikus tehetségéről ismert ...) ez a tipp:
Az egyik legegyszerűbb módszer a viccességre az, ha megfogalmazod a sajátosságodat, ha erre nincs szükség [… Példa:] A „különleges érdeklődés” helyett „balkezes avakádó-gazdák” mondanak.Végezze el a szkeptikus tesztet
Mielőtt a tervdokumentumot elküldené másoknak felülvizsgálatra, adja át a lapot úgy, mintha a lektor lenne. Milyen kérdései és kétségei lehetnek ezzel a tervvel kapcsolatban? Ezután megelőzően szóljon hozzájuk.
Végezze el a vakációs tesztet
Ha most hosszú nyaralásra indul, és nincs internet-hozzáférése, olvashatja-e valaki a csapatából a dokumentumot, és megvalósíthatja-e azt a szándéka szerint?
A tervezési dokumentum fő célja nem az ismeretek megosztása, de ez egy jó módszer az egyértelműség érdekében történő értékelésre, hogy mások valóban hasznos visszajelzéseket adhassanak Önnek.
Folyamat
Igen, a rettegett P-szó . A tervezési dokumentumok segítenek abban, hogy visszajelzést kapjon, mielőtt egy csomó időt pazarolna a rossz vagy a rossz probléma megoldására. Nagyon sok művészet rejlik abban, hogy jó visszajelzéseket kapjunk, de ez egy későbbi cikkhez szól. Egyelőre beszéljünk csak arról, hogy hogyan kell megírni a tervdokumentumot, és visszajelzést kapni róla.
Először is, mindenkinek, aki a projekten dolgozik, részt kell vennie a tervezési folyamatban. Nem baj, ha a technológiai vezető sok döntést meghozza, de mindenkit be kell vonni a megbeszélésbe, és beleszólni a tervezésbe. Tehát a „te” ebben a cikkben valóban többes számú „te”, amely magában foglalja a projekt összes emberét.
Másodszor, a tervezési folyamat nem azt jelenti, hogy az ötleteket elmélkedő táblára bámulja. Nyugodtan piszkosíthatja a kezét, és prototípusozhatja a lehetséges megoldásokat. Ez nem azonos azzal, hogy a tervdokumentum megírása előtt elkezdjük írni a projekt gyártási kódját. Ne csináld. De ha feltétlenül kell , bátran írj néhány hacky eldobható kódot, hogy érvényesítse az ötlet. Annak biztosítása érdekében, hogy csak felderítő kódot írjon, tegye szabálysá, hogy a prototípus kódok egyike sem kerül egyesítésre a masterrel .
Ezt követően, amikor elkezd ötletet kapni a projekt folytatásáról, tegye a következőket:
- Kérjen egy tapasztalt mérnököt vagy csapata műszaki vezetőjét, hogy legyen véleményezője. Ideális esetben ez olyan ember lenne, akit tiszteletben tartanak és / vagy ismerik a probléma szélsőséges eseteiben. Megvesztegetni őket boba, ha szükséges.
- Menjen be egy konferenciaterembe egy táblával.
- Írja le a problémát , amellyel ezzel a mérnökkel foglalkozik (ez egy nagyon fontos lépés, ne hagyja ki!).
- Ezután magyarázza el a tervezett megvalósítást , és győzze meg őket arról, hogy ez a helyes dolog.
Ha mindezt megteszi , még mielőtt elkezdené írni a tervdokumentumot, akkor mielőbb visszajelzést kaphat, mielőtt több időt fektetne be, és bármilyen konkrét megoldáshoz kötődne. Gyakran, még akkor is, ha a megvalósítás változatlan marad, az áttekintő képes rámutatni a lefedni kívánt sarok esetekre, megjelölni az esetleges zavart területeket, és előre jelezni a későbbi nehézségeket.
Ezután, miután megírta a tervdokumentumának durva vázlatát, kérje meg ugyanazt az ellenőrt, hogy olvassa el újra, és gumibélyegzővel adja hozzá nevét, mint bíráló a tervdokumentum Cím és emberek részéhez. Ez további ösztönzést és elszámoltathatóságot teremt a bíráló számára.
Ebből a szempontból fontolja meg speciális ellenőrök (például SRE-k és biztonsági mérnökök) felvételét a tervezés egyes aspektusaihoz.
Miután Ön és a véleményező (k) bejelentkeztek, nyugodtan küldje el a tervdokumentumot a csapatának további visszajelzés és tudásmegosztás céljából. Javaslom, hogy ezt a visszajelzés-összegyűjtési folyamatot kb. 1 hétre korlátozza a hosszabb késések elkerülése érdekében. Kötelezze magát arra, hogy foglalkozzon minden kérdéssel és megjegyzéssel, amelyet az emberek a héten hagynak. A megjegyzések lógása = rossz karma.
Végül, ha sok vita van köztetek, az áttekintő és a mérnököt olvasó más mérnökök között, erősen ajánlom, hogy az összes vitás kérdést konszolidálják a dokumentum Vita szakaszában. Ezután hozzon létre egy találkozót a különböző felekkel, hogy személyesen beszélhessen ezekről a nézeteltérésekről.
Ha egy beszélgetés szála hosszabb, mint 5 hozzászólás, akkor a személyes beszélgetésre való áttérés sokkal hatékonyabb lehet. Ne feledje, hogy Ön továbbra is felelős a végső felhívásért, még akkor is, ha mindenki nem tud konszenzusra jutni.
Amikor nemrég erről beszéltem Shrey Bangával, megtudtam, hogy a Quip-nek hasonló folyamata van, kivéve azt, hogy egy tapasztalt mérnök vagy technikai vezetés van a csapatában lektorként, azt is javasolják, hogy egy másik csapat mérnöke vizsgálja felül a dokumentumot. Még nem próbáltam, de biztosan látom, hogy ez segít visszajelzést kapni a különböző nézőpontokkal rendelkező emberektől, és javítja a dokumentum általános olvashatóságát.
Miután elvégezte a fentieket, ideje elkezdeni a megvalósítást! További brownie pontokért kezelje ezt a tervdokumentumot élő dokumentumként, amikor megvalósítja a tervet . Frissítse a dokumentumot minden alkalommal, amikor megtud valamit, ami arra készteti, hogy módosítsa az eredeti megoldást, vagy frissítse a hatókörét. Később megköszönöd, amikor nem kell újra és újra elmagyaráznod a dolgokat az összes érdekelt félnek.
Végül vegyünk egy pillanatra igazán metát: Hogyan értékeljük a tervdokumentum sikerét?
Kent Rakip munkatársam erre jó választ ad: A tervdokumentum akkor sikeres, ha a munka megfelelő megtérülése megtörtént. Ez azt jelenti, hogy egy sikeres tervdokumentum valóban ilyen eredményhez vezethet:
- Öt napot töltesz a tervdokumentum megírásával, ez arra kényszerít, hogy gondolkodj el a műszaki architektúra különböző részein
- Visszajelzést kap
Xa bírálóktól, ami a javasolt architektúra legkockázatosabb része XElőször úgy dönt, hogy először végrehajtja a projekt kockázatának csökkentését- 3 nappal később rájössz, hogy
Xvagy nem lehetséges, vagy sokkal nehezebb, mint eredetileg szántad - Úgy dönt, hogy abbahagyja a munkát ezen a projekten, és más munkákat helyez előtérbe
A cikk elején azt mondtuk, hogy egy tervezési dokumentum célja a megfelelő munka elvégzése. A fenti példában ennek a tervdokumentumnak köszönhető, hogy ahelyett, hogy esetleg hónapokat pazarolna csak a projekt későbbi megszakításához, csak 8 napot töltött. Elég sikeres eredménynek tűnik számomra.
Kérjük, hagyjon megjegyzést alább, ha bármilyen kérdése vagy visszajelzése van! Szívesen hallanék arról is, hogy másképp tervezed a dokumentumokat a csapatodban.
Hitelként odaadva, ahol a hitel esedékes, sok mindent megtanultam azzal, hogy néhány hihetetlen mérnök mellett dolgoztam a Plaidnél (felveszünk! Gyere tervezz és építs magunkkal néhány kedves műszaki rendszert) és a Quoránál.
Ha tetszik ez a bejegyzés, kövessen a Twitteren, ha további bejegyzéseket szeretne találni a mérnöki, a folyamatok és a háttérrendszerekről.