Jak napisać dobry dokument do projektowania oprogramowania

Jako inżynier oprogramowania spędzam dużo czasu na czytaniu i pisaniu dokumentów projektowych. Po przejrzeniu setek tych dokumentów, z pierwszej ręki zauważyłem silną korelację między dobrymi dokumentami projektowymi a ostatecznym sukcesem projektu.

Ten artykuł jest moją próbą opisania, co sprawia, że ​​dokument projektowy jest wspaniały .

Artykuł jest podzielony na 4 części:

  • Po co pisać dokument projektowy
  • Co zawrzeć w dokumencie projektowym
  • Jak to napisać
  • Proces wokół niego

Po co pisać dokument projektowy?

Dokument projektowy - znany również jako specyfikacja techniczna - to opis tego, jak planujesz rozwiązać problem.

Istnieje już wiele artykułów na temat tego, dlaczego ważne jest, aby napisać dokument projektowy przed zanurzeniem się w kodowaniu. Więc wszystko, co tu powiem, to:

Dokument projektowy jest najbardziej przydatnym narzędziem do upewnienia się, że wykonano właściwą pracę.

Głównym celem dokumentu projektowego jest zwiększenie efektywności poprzez zmuszenie do przemyślenia projektu i zebrania opinii od innych. Ludziom często wydaje się, że celem dokumentacji projektowej jest nauczenie innych o jakimś systemie lub późniejsze posłużenie jako dokumentacja. Chociaż te mogą być korzystne skutki uboczne, są nie celem samym w sobie.

Generalnie, jeśli pracujesz nad projektem, który może zająć 1 miesiąc inżyniera lub więcej, powinieneś napisać dokument projektowy. Ale nie poprzestawaj na tym - wiele mniejszych projektów może również skorzystać na mini dokumencie projektowym.

Świetny! Jeśli nadal czytasz, wierzysz w znaczenie dokumentacji projektowej. Jednak różne zespoły inżynierów, a nawet inżynierowie w tym samym zespole, często piszą dokumenty projektowe w bardzo różny sposób. Porozmawiajmy więc o treści, stylu i procesie tworzenia dobrego dokumentu projektowego.

Co zawrzeć w dokumencie projektowym?

Dokument projektowy opisuje rozwiązanie problemu. Ponieważ natura każdego problemu jest inna, naturalnie chciałbyś inaczej zorganizować dokument projektowy.

Na początek poniżej znajduje się lista sekcji, które powinieneś przynajmniej wziąć pod uwagęw następnym dokumencie projektowym:

Tytuł i ludzie

Tytuł dokumentu projektowego, plikautor (zy) (powinien być taki sam, jak lista osób planujących pracę nad tym projektem), recenzent (y)dokumentu (powiemy o tym więcej w sekcji Proces poniżej) i datę ostatniej aktualizacji tego dokumentu.

Przegląd

Podsumowanie wysokiego poziomu, które każdy inżynier w firmie powinien zrozumieć i wykorzystać, aby zdecydować, czy przeczytanie pozostałej części dokumentu będzie dla nich przydatne. Powinien mieć maksymalnie 3 punkty.

Kontekst

Opis problemu, dlaczego ten projekt jest konieczny, co ludzie powinni wiedzieć, aby ocenić ten projekt i jak pasuje on do strategii technicznej, strategii produktu lub kwartalnych celów zespołu.

Cele i inne niż cele

Sekcja Cele powinna:

  • opisz wpływ swojego projektu na użytkownika - w przypadku gdy Twoim użytkownikiem może być inny zespół inżynierów lub nawet inny system techniczny
  • określ, jak mierzyć sukces za pomocą metryk - punkty dodatkowe, jeśli możesz połączyć się z pulpitem nawigacyjnym, który śledzi te wskaźniki

Cele inne niż cele są równie ważne, aby opisać problemy, których nie naprawisz, aby wszyscy byli na tej samej stronie.

Kamienie milowe

Lista mierzalnych punktów kontrolnych, aby kierownik projektu i kierownik twojego kierownika mogli ją przejrzeć i z grubsza wiedzieć, kiedy różne części projektu zostaną wykonane. Zachęcam do podzielenia projektu na główne kamienie milowe dla użytkowników, jeśli projekt jest dłuższy niż 1 miesiąc.

Używaj dat kalendarza, aby brać pod uwagę niepowiązane opóźnienia, wakacje, spotkania itd. Powinien wyglądać mniej więcej tak:

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

Dodaj [Update]podsekcję w tym miejscu, jeśli ETA niektórych z tych kamieni milowych ulegnie zmianie, aby interesariusze mogli łatwo zobaczyć najbardziej aktualne szacunki.

Istniejące rozwiązanie

Oprócz opisu bieżącej implementacji należy również przejść przez ogólny przykład przepływu, aby zilustrować, w jaki sposób użytkownicy wchodzą w interakcję z tym systemem i / lub przepływają przez niego dane.

użytkownikfabułato świetny sposób na oprawienie tego. Pamiętaj, że Twój system może mieć różnych typów użytkowników z różnymi przypadkami użycia.

Proponowane rozwiązanie

Niektórzy nazywają to sekcją Architektury Technicznej . Ponownie spróbuj przejrzeć historię użytkownika, aby to skonkretyzować. Zapraszam do dołączenia wielu podsekcji i diagramów.

Najpierw przedstaw duży obraz, a następnie wypełnij dużozDetale. Celuj w świat, w którym możesz to napisać, a następnie weź urlop na jakiejś bezludnej wyspie, a inny inżynier z zespołu może po prostu to przeczytać i wdrożyć rozwiązanie zgodnie z opisem.

Alternatywne rozwiązania

Co jeszcze wziąłeś pod uwagę, wymyślając powyższe rozwiązanie? Jakie są wady i zalety tych alternatyw? Czy rozważałeś zakup rozwiązania innej firmy - lub skorzystanie z rozwiązania typu open source - które rozwiązuje ten problem, zamiast budować własne?

Testowalność, monitorowanie i ostrzeganie

Lubię włączać tę sekcję, ponieważ ludzie często traktują to jako refleksję lub pomijają to wszystko razem i prawie zawsze wraca, aby ich ugryźć później, gdy coś się psuje i nie mają pojęcia, jak i dlaczego.

Wpływ między zespołami

Jak wzrośnie to obciążenie związane z rozmowami i programistami?

Ile to będzie kosztować?

Czy powoduje cofanie się latencji do systemu?

Czy ujawnia jakieś luki w zabezpieczeniach?

Jakie są negatywne konsekwencje i skutki uboczne?

W jaki sposób zespół wsparcia może przekazać to klientom?

Otwarte pytania

Wszelkie otwarte kwestie, których nie jesteś pewien, kontrowersyjne decyzje, które chcesz, aby czytelnicy zważali, sugerowane przyszłe prace i tak dalej. Żartobliwa nazwa tej sekcji to „znane niewiadome”.

Szczegółowy zakres i oś czasu

Ta sekcja będzie w większości przeznaczona tylko dla inżynierów pracujących nad tym projektem, ich liderów technicznych 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. Dokładne określanie zakresu wymaga wiele, więc możesz przeczytać ten post, aby dowiedzieć się więcej o określaniu zakresu.

Zwykle również traktuję tę sekcję dokumentu projektowego jako narzędzie do śledzenia bieżących zadań projektu, więc aktualizuję to za każdym razem, gdy zmieni się mój szacunek zakresu. Ale to bardziej osobiste preferencje.

Jak to napisać

Skoro omówiliśmy już, co składa się na dobry dokument projektowy, porozmawiajmy o stylu pisania. Obiecuję, że to coś innego niż twoje lekcje angielskiego w liceum.

Pisz tak prosto, jak to tylko możliwe

Nie próbuj pisać jak artykuły naukowe, które czytałeś. Zostały napisane, aby zaimponować recenzentom czasopism. Twój dokument ma na celu opisanie rozwiązania i uzyskanie opinii od członków zespołu. Możesz osiągnąć przejrzystość, używając:

  • Proste słowa
  • Krótkie zdania
  • Listy wypunktowane i / lub listy numerowane
  • Konkretne przykłady, np. „Użytkownik Alice łączy swoje konto bankowe, a następnie…”

Dodaj dużo wykresów i diagramów

Wykresy często mogą być przydatne do porównywania kilku potencjalnych opcji, a diagramy są generalnie łatwiejsze do przeanalizowania niż tekst. Miałem szczęście z Google Drawing do tworzenia diagramów.

Wskazówka dla profesjonalistów: pamiętaj, aby dodać link do edytowalnej wersji diagramu pod zrzutem ekranu, abyś mógł go łatwo zaktualizować później, gdy coś się nieuchronnie zmieni.

Uwzględnij liczby

Skala problemu często determinuje rozwiązanie. Aby pomóc recenzentom w zrozumieniu stanu świata, uwzględnij liczby rzeczywiste, takie jak liczba wierszy bazy danych, liczba błędów użytkowników, opóźnienie - i sposób, w jaki te skalują się wraz z użyciem. Pamiętasz swoje notacje Big-O?

Spróbuj być zabawny

Specyfikacja nie jest pracą naukową. Poza tym ludzie lubią czytać śmieszne rzeczy, więc jest to dobry sposób na utrzymanie zaangażowania czytelnika. Nie przesadzaj jednak do tego stopnia, że ​​odejdziesz od głównej idei.

Jeśli ty, tak jak ja, nie możesz być zabawny, Joel Spolsky ( znany oczywiście ze swoich talentów komediowych…) ma następującą wskazówkę:

Jednym z najłatwiejszych sposobów bycia zabawnym jest bycie konkretnym, gdy nie jest to wymagane [… Przykład:] Zamiast mówić „szczególne zainteresowania”, powiedz „leworęczni hodowcy awakado”.

Zrób test sceptyczny

Przed wysłaniem dokumentu projektowego do innych w celu przejrzenia, przejdź do niego udając recenzenta. Jakie pytania i wątpliwości możesz mieć odnośnie tego projektu? Następnie zajmij się nimi zapobiegawczo.

Wykonaj 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 zamierzeniami?

Głównym celem dokumentu projektowego nie jest dzielenie się wiedzą, ale jest to dobry sposób oceny pod kątem jasności, tak aby inni mogli faktycznie przekazać przydatne informacje zwrotne.

Proces

Ach tak, bał P-słowo . Dokumentacja projektowa pomaga uzyskać informacje zwrotne, zanim zmarnujesz trochę czasu na wdrażanie niewłaściwego rozwiązania lub rozwiązania niewłaściwego problemu. Uzyskanie dobrych opinii jest nie lada sztuką, ale to na późniejszy artykuł. Na razie porozmawiajmy konkretnie o tym, jak napisać dokument projektu i uzyskać na jego temat opinię.

Przede wszystkim każdy, kto pracuje nad projektem, powinien być częścią procesu projektowego. Nie ma problemu, jeśli kierownik ds. Technologii ostatecznie podejmuje wiele decyzji, ale wszyscy powinni wziąć udział w dyskusji i wkupić się w projekt. Zatem „ty” w tym artykule to naprawdę liczba mnoga „ty”, która obejmuje wszystkie osoby biorące udział w projekcie.

Po drugie, proces projektowania nie oznacza, że ​​wpatrujesz się w pomysły teoretyczne tablicy. Zapraszam do zabrudzenia 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ś hakerski, jednorazowy kod, aby zweryfikować pomysł. Aby mieć pewność, że piszesz tylko kod eksploracyjny, utwórz regułę, że żaden z tego prototypowego kodu nie zostanie scalony z wzorcem .

Następnie, gdy zaczniesz mieć pojęcie o tym, jak zająć się swoim projektem, wykonaj następujące czynności:

  1. Poproś doświadczonego inżyniera lub kierownika technicznego w swoim zespole, aby został recenzentem. Idealnie byłoby, gdyby był to ktoś, kto jest szanowany i / lub zaznajomiony z skrajnymi przypadkami problemu. Jeśli to konieczne, przekup je boba.
  2. Wejdź do sali konferencyjnej z tablicą.
  3. Opisz temu inżynierowi problem , którym się zajmujesz (to bardzo ważny krok, nie pomijaj go!).
  4. Następnie wyjaśnij implementację, którą masz na myśli, i przekonaj ich, że jest to właściwa rzecz.

Wykonanie tego wszystkiego, zanim jeszcze zaczniesz pisać dokument projektowy, pozwoli Ci uzyskać opinię tak szybko, jak to możliwe, zanim zainwestujesz więcej czasu i przywiążesz się do konkretnego rozwiązania. Często, nawet jeśli implementacja pozostaje taka sama, recenzent jest w stanie wskazać krytyczne przypadki, które należy uwzględnić, wskazać potencjalne obszary zamieszania i przewidzieć trudności, które możesz napotkać później.

Następnie, po napisaniu wstępnej wersji roboczej dokumentu projektowego, poproś tego samego recenzenta, aby ponownie go przeczytał, i pieczęć go, dodając jego nazwisko jako recenzenta w sekcji Tytuł i osoby w dokumencie projektu. Stwarza to dodatkową zachętę i odpowiedzialność dla recenzenta.

W tej notatce rozważ dodanie wyspecjalizowanych recenzentów (takich jak SRE i inżynierowie bezpieczeństwa) dla określonych aspektów projektu.

Po podpisaniu przez Ciebie i recenzenta (y) możesz wysłać dokument projektu do swojego zespołu, aby uzyskać dodatkowe opinie i podzielić się wiedzą. Sugeruję ograniczenie czasu procesu zbierania opinii do około 1 tygodnia, aby uniknąć dłuższych opóźnień. Postaraj się odpowiedzieć na wszystkie pytania i komentarze, które ludzie opuszczają w ciągu tego tygodnia. Pozostawienie wiszących komentarzy = zła karma.

Na koniec, jeśli między Tobą, Twoim recenzentem i innymi inżynierami czytającymi dokument jest dużo niezgody, zdecydowanie zalecam skonsolidowanie wszystkich punktów spornych w sekcji Dyskusja w dokumencie. Następnie umów się na spotkanie z różnymi stronami, aby osobiście porozmawiać o tych nieporozumieniach.

Ilekroć wątek w dyskusji ma więcej niż 5 komentarzy, przejście do rozmowy osobistej jest znacznie bardziej efektywne. Pamiętaj, że nadal jesteś odpowiedzialny za ostateczne wezwanie, nawet jeśli wszyscy nie mogą dojść do porozumienia.

Rozmawiając o tym niedawno z Shrey Bangą, dowiedziałem się, że Quip ma podobny proces, z wyjątkiem tego, że oprócz posiadania doświadczonego inżyniera lub kierownika technicznego w twoim zespole jako recenzenta, sugerują również, aby inżynier z innego zespołu sprawdził dokument. Nie próbowałem tego, ale z pewnością widzę, że pomaga to uzyskać informacje zwrotne od ludzi o różnych perspektywach i poprawić ogólną czytelność dokumentu.

Po wykonaniu wszystkich powyższych czynności czas przystąpić do wdrażania! Aby uzyskać dodatkowe punkty, traktuj ten dokument projektu jako żywy dokument podczas wdrażania projektu . Zaktualizuj dokument za każdym razem, gdy dowiesz się czegoś, co prowadzi do wprowadzenia zmian w oryginalnym rozwiązaniu lub zaktualizowania zakresu. Podziękujesz mi później, kiedy nie będziesz musiał w kółko wyjaśniać wszystkim swoim interesariuszom.

Na koniec przejdźmy przez chwilę do naprawdę meta: Jak oceniamy sukces dokumentacji projektowej?

Mój współpracownik Kent Rakip ma dobrą odpowiedź na to pytanie: dokument projektowy jest skuteczny, jeśli wykonano właściwy zwrot z inwestycji. Oznacza to, że udany dokument projektowy może w rzeczywistości doprowadzić do takiego wyniku:

  1. Spędzasz 5 dni na pisaniu dokumentacji projektowej, co zmusza cię do przemyślenia różnych części architektury technicznej
  2. Otrzymujesz opinie od recenzentów, które Xsą najbardziej ryzykowną częścią proponowanej architektury
  3. Decydujesz się Xnajpierw wdrożyć, aby zmniejszyć ryzyko projektu
  4. 3 dni później okaże się, że Xalbo nie jest to możliwe, albo jest to dużo trudniejsze niż pierwotnie zamierzałeś
  5. Decydujesz się przerwać pracę nad tym projektem i zamiast tego nadać priorytet innej pracy

Na początku tego artykułu powiedzieliśmy, że celem dokumentu projektowego jest upewnienie się, że wykonano właściwą pracę. W powyższym przykładzie, dzięki temu dokumentowi projektowemu, zamiast tracić potencjalnie miesiące tylko na późniejsze przerwanie tego projektu, spędziłeś tylko 8 dni. Wydaje mi się, że to całkiem udany wynik.

Jeśli masz jakieś pytania lub uwagi, zostaw komentarz poniżej! Chciałbym również usłyszeć, jak inaczej projektujesz dokumenty w swoim zespole.

Dając uznanie, nauczyłem się wielu z powyższego, pracując razem z niesamowitymi inżynierami w firmie Plaid (zatrudniamy! Przyjdź zaprojektuj i zbuduj z nami wspaniałe systemy techniczne) i Quora.

Jeśli podoba Ci się ten post, śledź mnie na Twitterze, aby uzyskać więcej wpisów dotyczących inżynierii, procesów i systemów zaplecza.