Angela Zhang
jako inżynier oprogramowania spędzam dużo czasu na czytaniu i pisaniu dokumentów projektowych. Po przejściu setek tych dokumentów z pierwszej ręki widziałem silną korelację między dobrymi dokumentami projektowymi a ostatecznym sukcesem projektu.
Ten artykuł jest moją próbą opisania tego, co sprawia, że dokument projektowy jest świetny.,
artykuł jest podzielony na 4 sekcje:
- po co pisać dokument projektowy
- co zawierać w dokumencie projektowym
- jak go napisać
- proces wokół niego
po co pisać dokument projektowy?
dokument projektowy — znany również jako spec techniczny — to opis sposobu, w jaki planujesz rozwiązać problem.
jest już wiele napisów na temat tego, dlaczego ważne jest, aby napisać projekt doc przed zagłębianiem się w kodowanie. Więc powiem tylko tyle:
dokument projektowy jest najbardziej użytecznym narzędziem do upewnienia się, że odpowiednia praca zostanie wykonana.,
głównym celem projektu DOC jest uczynienie cię bardziej efektywnym, zmuszając cię do przemyślenia projektu i zebrania opinii od innych. Ludzie często myślą, że celem dokumentu design doc jest nauczenie innych o jakimś systemie lub służenie później jako dokumentacja. Chociaż mogą to być korzystne skutki uboczne, nie są one celem samym w sobie.
ogólnie rzecz biorąc, jeśli pracujesz nad projektem, który może potrwać 1 miesiąc lub dłużej, powinieneś napisać dokument projektowy. Ale nie zatrzymuj się na tym — wiele mniejszych projektów może również skorzystać z mini design doc.
świetnie!, Jeśli nadal czytasz, wierzysz w znaczenie dokumentów projektowych. Jednak różne zespoły inżynierskie, a nawet inżynierowie w tym samym zespole, często piszą dokumenty projektowe bardzo inaczej. Porozmawiajmy więc o treści, stylu i procesie dobrego dokumentu projektowego.
co zawierać w dokumencie projektowym?
dokument projektowy opisuje rozwiązanie problemu. Ponieważ charakter każdego problemu jest inny, naturalnie chciałbyś inaczej skonstruować swój dokument projektowy.,
aby rozpocząć, poniżej znajduje się lista sekcji, które powinieneś przynajmniej rozważyć w swoim następnym dokumencie design:
Title i People
tytuł twojego dokumentu design, autorzy(powinni być tacy sami jak lista osób planujących pracować nad tym projektem), recenzenci dokumentu (o tym porozmawiamy w sekcji Proces poniżej) oraz Data ostatniej aktualizacji tego dokumentu.
przegląd
podsumowanie wysokiego poziomu, które każdy inżynier w firmie powinien zrozumieć i wykorzystać, aby zdecydować, czy jest dla niego przydatne przeczytanie reszty dokumentu., Powinno to być maksymalnie 3 akapity.
kontekst
opis problemu, dlaczego ten projekt jest konieczny, co ludzie muszą wiedzieć, aby ocenić ten projekt i jak wpisuje się on w strategię techniczną, strategię produktową lub kwartalne cele zespołu.,
cele i inne cele
sekcja cele powinna:
- opisać wpływ projektu na użytkownika-gdzie Twoim użytkownikiem może być inny zespół inżynierów lub nawet inny system techniczny
- określić, jak mierzyć sukces za pomocą wskaźników-punkty bonusowe, jeśli możesz połączyć się z pulpitem nawigacyjnym, który śledzi te wskaźniki
cele nie są równie ważne, aby opisać, które problemy nie zostaną naprawione, więc wszyscy są na tej samej stronie.,
kamienie milowe
lista mierzalnych punktów kontrolnych, dzięki czemu twój premier i kierownik twojego menedżera mogą je przejrzeć i wiedzieć z grubsza, kiedy zostaną wykonane różne części projektu. Zachęcam do podzielenia projektu na główne kamienie milowe dla użytkowników, jeśli projekt trwa dłużej niż 1 miesiąc.
użyj dat kalendarzowych, aby wziąć pod uwagę niepowiązane opóźnienia, wakacje, spotkania i tak dalej., Powinno to wyglądać mniej więcej tak:
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
Dodaj podsekcja tutaj, jeśli eta niektórych z tych przełomowych zmian, więc interesariusze mogą łatwo zobaczyć najbardziej aktualne szacunki.
Istniejące rozwiązanie
oprócz opisania bieżącej implementacji, należy również przejść przez przykładowy przepływ wysokiego poziomu, aby zilustrować, w jaki sposób użytkownicy wchodzą w interakcję z tym systemem i / lub jak przepływają przez niego dane.,
a user story is a great way to frame this. Pamiętaj, że Twój system może mieć różne typy użytkowników o różnych przypadkach użycia.
proponowane rozwiązanie
niektórzy nazywają to sekcją architektury technicznej. Ponownie spróbuj przejść przez historię użytkownika, aby to konkretyzować. Zapraszam do dołączania wielu podrozdziałów i diagramów.
podaj najpierw duży obraz, a następnie wypełnij wiele szczegółów. Celuj w świat, w którym możesz to napisać, a następnie wziąć urlop na bezludnej wyspie, a inny inżynier w zespole może go po prostu przeczytać i wdrożyć rozwiązanie zgodnie z opisem.,
alternatywne rozwiązania
Co jeszcze wzięliście pod uwagę przy opracowywaniu powyższego rozwiązania? Jakie są plusy i minusy alternatyw? Czy rozważałeś zakup rozwiązania innych firm – lub użycie open source-które rozwiązuje ten problem w przeciwieństwie do budowania własnego?
Testowalność, monitorowanie i alarmowanie
podoba mi się Ta sekcja, ponieważ ludzie często traktują to jako przemyślenie lub pomijają to wszystko razem, i prawie zawsze wraca, aby ugryźć ich później, gdy coś się zepsuje i nie mają pojęcia, jak i dlaczego.,
wpływ Cross-Team
w jaki sposób zwiększy to obciążenie on call i dev-ops?
ile to będzie kosztować?
Czy powoduje regresję opóźnień w układzie?
Czy ujawnia jakieś luki w zabezpieczeniach?
jakie są jakieś negatywne konsekwencje i skutki uboczne?
w jaki sposób zespół wsparcia może przekazać to klientom?
pytania otwarte
wszelkie otwarte kwestie, których nie jesteś pewien, kontrowersyjne decyzje, które chciałbyś, aby czytelnicy ważyli, sugerowali przyszłe prace i tak dalej. Nazwa tego odcinka to „znane niewiadome”.,
szczegółowy zakres i oś czasu
Ta sekcja będzie w większości odczytywana tylko przez inżynierów pracujących nad tym projektem, ich liderów technologicznych i ich menedżerów. Stąd ta sekcja znajduje się na końcu dokumentu.
zasadniczo jest to zestawienie tego, jak i kiedy planujesz wykonać każdą część projektu. Jest wiele rzeczy, które dokładnie dotyczą zakresu, więc możesz przeczytać ten post, aby dowiedzieć się więcej na temat zakresu.
Zwykle traktuję tę sekcję dokumentu design jako śledzenie zadań projektu, więc aktualizuję ją za każdym razem, gdy zmienia się mój szacowany zakres., Ale to raczej osobiste preferencje.
Jak to napisać
teraz, gdy rozmawialiśmy o tym, co idzie do dobrego dokumentu projektowego, porozmawiajmy o stylu pisania. Obiecuję, że to coś innego niż twoja klasa z angielskiego.
pisz jak najprościej
nie próbuj pisać tak, jak czytałeś. Są one napisane, aby zaimponować recenzentom czasopism. Twój dokument jest napisany w celu opisania Twojego rozwiązania i uzyskania opinii od kolegów z zespołu., Możesz osiągnąć jasność za pomocą:
- proste słowa
- krótkie zdania
- listy punktowane i/lub listy numerowane
- konkretne przykłady, takie jak „użytkownik Alice łączy swoje konto bankowe, a następnie …”
Dodaj wiele wykresów i diagramów
wykresy mogą być często przydatne do porównania kilku potencjalnych opcji, a diagramy są na ogół łatwiejsze do przetworzenia niż tekst. Miałem szczęście z rysowaniem Google do tworzenia diagramów.,
Pro Wskazówka: pamiętaj, aby dodać link do edytowalnej wersji diagramu pod zrzutem ekranu, abyś mógł go łatwo zaktualizować później, gdy rzeczy nieuchronnie się zmienią.
Dołącz liczby
skala problemu często determinuje rozwiązanie. Aby pomóc recenzentom w zrozumieniu stanu świata, dołącz liczby rzeczywiste , takie jak # wierszy DB, # błędów użytkownika, opóźnienia — i jak te skalują się wraz z użyciem. Pamiętasz notacje Big-O?
staraj się być zabawny
spec to nie praca naukowa. Ponadto ludzie lubią czytać zabawne rzeczy, więc jest to dobry sposób na zaangażowanie czytelnika., Nie przesadzaj z tym do tego stopnia, że odchodzisz od głównej idei.
Jeśli, podobnie jak ja, masz problem z byciem zabawnym, Joel Spolsky (oczywiście znany ze swoich komediowych talentów…) ma tę wskazówkę:
jednym z najprostszych sposobów na bycie zabawnym jest bycie konkretnym, gdy nie jest wymagane zamiast mówić „specjalne zainteresowania”, powiedzieć „leworęczni rolnicy avacado.”
wykonaj test sceptyczny
zanim wyślesz swój dokument projektowy do innych osób, przejrzyj go udając recenzenta. Jakie masz pytania i wątpliwości dotyczące tego projektu?, Więc zwracaj się do nich prewencyjnie.
Zrób test wakacyjny
Jeśli wybierasz się teraz na długie wakacje bez dostępu do Internetu, czy ktoś z twojego zespołu może przeczytać dokument i wdrożyć go zgodnie z twoim zamiarem?
głównym celem projektu doc nie jest dzielenie się wiedzą, ale jest to dobry sposób na jasną ocenę, aby inni mogli przekazać ci przydatne informacje zwrotne.
Process
Ach tak, przerażające słowo P., Dokumenty projektowe pomagają uzyskać informacje zwrotne, zanim stracisz trochę czasu na wdrożenie niewłaściwego rozwiązania lub rozwiązania niewłaściwego problemu. Jest wiele sztuki, aby uzyskać dobre opinie, ale to jest do późniejszego artykułu. Na razie porozmawiajmy konkretnie o tym, jak napisać projekt doc i uzyskać opinie na jego temat.
przede wszystkim każdy pracujący nad projektem powinien być częścią procesu projektowania. To w porządku, jeśli Tech lead kończy się napędza wiele decyzji, ale każdy powinien być zaangażowany w dyskusję i kupić projekt., Tak więc ” ty „w tym artykule jest naprawdę mnogim „ty”, który obejmuje wszystkich ludzi w projekcie.
Po drugie, proces projektowania nie oznacza, że gapisz się na pomysły teoretyzujące tablicę. Zapraszam do zabrudzenia sobie rąk i prototypowania potencjalnych rozwiązań. To nie to samo, co rozpoczęcie pisania kodu produkcyjnego dla projektu przed napisaniem dokumentu projektowego. Nie rób tego. Ale absolutnie powinieneś czuć się swobodnie, aby napisać jakiś hacky throwaway kod, aby potwierdzić pomysł., Aby mieć pewność, że piszesz tylko kod rozpoznawczy, należy wprowadzić zasadę, że żaden z tego prototypowego kodu nie zostanie scalony do master.
Po tym, jak zaczniesz mieć jakiś pomysł, jak przejść do swojego projektu, wykonaj następujące czynności:
- poproś doświadczonego inżyniera lub kierownika technicznego w swoim zespole, aby został Twoim recenzentem. Idealnie byłoby to ktoś, kto jest dobrze szanowany i / lub zna przypadki krawędzi problemu. Przekup ich bobą, jeśli to konieczne.
- wejdź do sali konferencyjnej z tablicą.,
- opisz problem, z którym masz do czynienia temu inżynierowi (jest to bardzo ważny krok, nie pomijaj go!).
- następnie wyjaśnij implementację, którą masz na myśli, i przekonaj ich, że jest to właściwa rzecz do zbudowania.
robiąc to wszystko, zanim zaczniesz pisać dokument projektowy, Otrzymasz jak najszybciej informacje zwrotne, zanim zainwestujesz więcej czasu i przywiązasz się do konkretnego rozwiązania., Często, nawet jeśli implementacja pozostaje taka sama, recenzent jest w stanie wskazać narożne przypadki, które musisz objąć, wskazać potencjalne obszary zamieszania i przewidzieć trudności, które możesz napotkać w późniejszym czasie.
następnie, po napisaniu szkicu dokumentu design, poproś tego samego recenzenta, aby przeczytał go ponownie i stempel gumowy, dodając jego imię jako recenzent w sekcji tytuł i ludzie dokumentu design. Stwarza to dodatkową zachętę i odpowiedzialność dla recenzenta.,
w tej kwestii rozważ dodanie wyspecjalizowanych recenzentów (takich jak Sre i inżynierowie bezpieczeństwa) dla konkretnych aspektów projektu.
po wylogowaniu się wraz z recenzentem możesz wysłać dokument design do swojego zespołu, aby uzyskać dodatkowe informacje zwrotne i podzielić się wiedzą. Sugeruję ograniczenie czasu tego procesu zbierania informacji zwrotnych do około 1 tygodnia, aby uniknąć wydłużonych opóźnień. Zobowiązać się do odpowiadania na wszystkie pytania i komentarze, które ludzie zostawiają w tym tygodniu. Pozostawienie komentarzy wiszących = zła karma.,
wreszcie, jeśli jest wiele sporów między tobą, twoim recenzentem i innymi inżynierami czytającymi doc, zdecydowanie polecam skonsolidowanie wszystkich punktów spornych w sekcji dyskusji twojego doc. Następnie umów się na spotkanie z różnymi stronami, aby porozmawiać o tych niezgodnościach osobiście.
ilekroć wątek dyskusyjny ma więcej niż 5 komentarzy, przejście do osobistej dyskusji wydaje się o wiele bardziej efektywne. Pamiętaj, że nadal jesteś odpowiedzialny za ostateczne połączenie, nawet jeśli wszyscy nie mogą dojść do konsensusu.,
rozmawiając ostatnio z Shreyem Bangą o tym, dowiedziałem się, że Quip ma podobny proces, z wyjątkiem tego, że oprócz posiadania doświadczonego inżyniera lub lidera technicznego w zespole jako recenzenta, sugerują również, że inżynier w innym zespole recenzuje dokument. Nie próbowałem tego, ale z pewnością widzę, że pomaga to uzyskać informacje zwrotne od osób z różnymi perspektywami i poprawić ogólną czytelność dokumentu.
Po wykonaniu wszystkich powyższych czynności czas rozpocząć realizację!, Aby uzyskać dodatkowe punkty brownie, traktuj ten dokument projektowy jako żywy dokument podczas wdrażania projektu. Aktualizuj dokument za każdym razem, gdy nauczysz się czegoś, co prowadzi do wprowadzenia zmian w oryginalnym rozwiązaniu lub zaktualizowania zakresu. Podziękujesz mi później, kiedy nie będziesz musiał wyjaśniać wszystkiego w kółko wszystkim swoim interesariuszom.
na koniec przejdźmy przez chwilę do rzeczy: jak oceniamy sukces projektu Doc?
mój współpracownik Kent Rakip ma na to dobrą odpowiedź: projekt doc jest udany, jeśli zostanie wykonany odpowiedni zwrot z pracy.,ts architektury technicznej
X jest najbardziej ryzykowną częścią proponowanej architekturyX po pierwsze, aby zmniejszyć ryzyko projektuX jest to albo niemożliwe, albo znacznie trudniejsze niż pierwotnie zamierzałeśna początku tego artykułu powiedzieliśmy, że celem dokumentu design jest upewnienie się, że zostanie wykonana właściwa praca., W powyższym przykładzie, dzięki temu dokumentowi design, zamiast marnować potencjalnie miesiące, aby później przerwać ten projekt, spędziłeś tylko 8 dni. Wydaje mi się to całkiem udane.
proszę zostawić komentarz poniżej, jeśli masz jakieś pytania lub opinie! Chciałbym również usłyszeć o tym, jak inaczej robisz dokumenty projektowe w swoim zespole.
dając kredyt tam, gdzie kredyt jest należny, nauczyłem się wiele z powyższych, pracując u boku niesamowitych inżynierów w Plaid(zatrudniamy! Przyjdź zaprojektować i zbudować kilka słodkich systemów technicznych z nami) i Quora. ,
Jeśli podoba ci się ten post, Śledź mnie na Twitterze, aby uzyskać więcej postów na temat inżynierii, procesów i systemów zaplecza.