Jak napisać design doc (i nie przedobrzyć)?

Jak napisać design doc (i nie przedobrzyć)

Pracując nad jakimkolwiek projektem programistycznym – czy to osobistym projektem hobbystycznym, czy też pracując w poważnej firmie, jako jedna z wielu programistek tam zatrudnionych – dostajemy czasem olśnienia i inspiracji, i z wielką chęcią ruszamy do klawiatury i komputera, by jak najszybciej naklepać kod, który właśnie przyszedł nam do głowy. A najlepiej cały program! I czasem takie podejście faktycznie działa, ale dziś chciałabym opowiedzieć Ci o design docach, czyli dokumentacji projektu tworzonej, zanim jeszcze ten kod zaczniesz klepać oraz o dobrych (i tych mniej) praktykach pisania takiego dokumentu.

Wpis ten jest częścią cyklu “Projekt z PSS”. Przeczytaj także:

Po co komu design doc?

Design doc, czy też dokumentacja projektowa, to po prostu zapis planu projektu programistycznego – ważnych decyzji projektowych, ciekawych przypadków użycia i przykładów z tym związanych. Taki dokument pozwala naszkicować sobie w głowie, jak całość będzie wyglądać, zanim jeszcze powstanie pierwsza linijka kodu! To też dobry sposób, żeby zebrać komentarze i opinie od innych uczestników projektu oraz uchronić się przed popełnieniem oczywistych błędów, których nie zauważymy zalani rumieńcem ekscytacji w ferworze pracy.

Taki dokument z pewnością powinien powstać dla wszelkich dużych projektów, tworzonych z myślą o przyszłościowym wykorzystaniu i rozwoju, przez zespoły programistów. Warto jednak rozważyć przelanie na papier swoich pomysł i rozwiązań również w wypadku mniejszych projektów.

Design doc pozwala Ci spojrzeć na Twój projekt z lotu ptaka. Pracując nad implementacją, skupiasz się raczej na konkretnej części – wiesz na przykład, że użytkownik Twojego serwisu będzie publikować krótkie posty, notatki tak jak na Twitterze. Implementujesz więc na szybko rozwiązanie, które tworzy post oznaczony loginem użytkownika i dopiero później dociera do Ciebie, że Twój serwis powinien dać możliwość zmiany loginu… Być może przykład wydaje Ci się trywialny (a na pewno jest łatwy do naprawienia!), jednak pokazuje on, jak ważne jest czasem, by zatrzymać się i zastanowić nad całością, zanim zaczniemy pracować nad szczegółami. I tego typu pracę i myślenie wymusza na nas tworzenie design doców.

Planując swój projekt wcześniej, jesteś w stanie lepiej rozplanować swoją własną pracę i kolejne kamienie milowe. W jasny i klarowny sposób definiujesz najważniejsze elementy swojego projektu (tzw. MVP, czyli “minimal viable product”), bez których system nie mógłby działać. Wiesz jednak, co chcesz osiągnąć już później i na tej podstawie możesz podejmować kolejne decyzje projektowe. 

Dodatkowo tworzenie design doc pozwala przeanalizować różne przypadki użycia i jak Twój program powinien zachować się w danej sytuacji. Implementując oprogramowanie na podstawie dobrego design doca, nie musisz więcej zastanawiać się, co zrobić – po prostu siadasz i klepiesz, a wszelkie wątpliwości powinny być już rozwiane właśnie w Twoim dokumencie!

Ostatecznie – jeśli z jakiegoś powodu przerwiesz pracę nad projektem, by wrócić do niego po paru miesiącach – nie musisz wymyślać koła na nowo! Już raz wykonałaś tę pracę – rozważyłaś wszelkie scenariusze i zastanowiłaś się, dlaczego program powinien zachowywać się w konkretny sposób – z dokumentacją projektu szybko przypomnisz sobie, o co chodziło i odświeżysz wymagania, i będziesz mogła wziąć się do pracy dużo szybciej!

Projektuj, ale z umiarem!

Projektowanie oprogramowania to niesamowicie ważna umiejętność, sprawdzana przez pracodawców w czasie rekrutacji i pozwalająca ocenić poziom zaawansowania i doświadczenie kandydatki. Okazuje się jednak, że można też… “przeprojektować” (z angielskiego: overdesign), czyli zwyczajnie w świecie przesadzić z dokumentowaniem swojego projektu!
Nieskomplikowane projekty, składające się z jednego pliku czy jednej funkcji raczej nie potrzebują 3 stron A4 dokumentacji… W tym wypadku pracowanie nad design dociem to raczej skórka za wyprawkę. 

Nie wstydźmy się też przyznać, że wśród programistów raczej próżno szukać tych, którzy uwielbiają pisać dokumentację – dlatego też myśl o napisaniu design doca może raczej zniechęcać do pracy nad projektem. 
Dlatego też pamiętaj, że tworzenie dokumentacji projektowej i design doców jest ważne, ale należy do nich podchodzić z umiarem.

Skomplikowane projekty angażujące grupę programistów potrzebują znacznie więcej uwagi. W wypadku własnych projektów programistycznych, zwłaszcza tych początkujących, prawdopodobnie wystarczą Ci notatki na kartce. Chciałabym jednak, żeby spisanie wymagań, przykładów użycia i zastanowienie się nad corner case’ami stało się nieodłącznym elementem Twojej pracy nad kodem. Być może na początku wyda Ci się to nadmiarowe, ale uwierz mi – naprawdę zaprocentuje w przyszłości, w miarę rozwoju Twojej programistycznej kariery! W końcu zarówno nadmiar, ale i niedomiar są Twoimi wrogami! slightly smiling face

Jak napisać design doc? Elementy dobrego design doca

Pisanie dla samego pisania, tylko po to, żeby odhaczyć “zrobione” na liście zadań pod punktem o dokumentacji projektowej, nie ma większego sensu. Dokumentacja ma przynieść wartość, a praca, którą wykonasz, zastanawiając się nad swoim projektem, ma ułatwić Ci późniejszą pracę nad implementacją. Dobrze więc podejść do tego zadania strategicznie i zadbać o najważniejsze elementy.

Czym jest dany projekt?

Zacznij od opisania własnymi słowami głównej funkcjonalności programu. Co robi? Kim są użytkownicy? W jakim środowisku działa? Pomoże Ci to umieścić program w kontekście i ułatwi dalszą pracę. Nie zapomnij też opisać wymagań, jeśli takie istnieją.

Jakie są poszczególne komponenty i jak wygląda komunikacja między nimi?

Nawet w niewielkich projektach można wyróżnić kilka komponentów – ot, serwer i baza danych; serwer i klient; Twój serwis i zewnętrzne API… Dlatego też design doc powinien zawierać informację o tym, jakie są poszczególne komponenty i jak się komunikują między sobą – czy korzystasz ze specjalnej biblioteki? A może wykorzystujesz jakiś niestandardowy mechanizm? Wspomnij też o tym, dlaczego podjęłaś taką decyzję – i pamiętaj, że nie ma złych odpowiedzi! Jeśli zwyczajnie w świecie chciałaś spróbować nauczyć się korzystać z konkretnego narzędzia – po prostu to zaznacz. Koniecznie wspomnij o tym, jeśli Twoja decyzja była podyktowana konkretnym wymaganiem, czy analizą… 

Jakie są ciekawe scenariusze wykonania Twojego programu?

W przypadku niewielkiego programu, który pobiera dane z internetu, a następnie je odpowiednio przetwarza – ciekawym scenariuszem byłyby więc przypadki błędnych danych lub ich braku. Jeśli na przykład projektujesz narzędzie do pracy online, ciekawym scenariuszem będzie opisanie, jak Twój program się zachowa w przypadku przerwania połączenia (tymczasowego braku internetu). Jednym słowem – zastanów się po prostu, w jakich ciekawych sytuacjach mogą znaleźć się Twoi użytkownicy. Dzięki temu łatwiej będzie potem uwzględnić je w swojej implementacji!

Co dalej?

Taki dokument może być świetnym wstępem do dokumentacji Twojego projektu. Jeśli udostępniasz swój projekt w serwisie github – dodaj treść swojego design doca jako README projektu! Pokażesz tym samym, że traktujesz swój projekt profesjonalnie, a przy tym dasz możliwość innym osobom, które znajdą Twój profil szybkiego wdrożenia się w Twoją implementację.

Dobrym rozwiązaniem może być też wysłanie takiego dokumentu znajomym programistom z prośbą o opinie – być może będą w stanie coś podpowiedzieć, a Ty nauczysz się czegoś nowego. Być może będą Cię chwalić za rozbrojenie problemu na drobne części! 

Jeśli pracujesz z zespołem programistów, design doc pozwoli Wam wszystkim skonsolidować przemyślenia na temat projektu i wspólnie wyznaczyć drogę do celu. Dlatego też koniecznie podziel się nim z innymi!


Mam nadzieję, że po przeczytaniu tego tekstu wiesz już, jak napisać design doc i właśnie od tego zaczniesz pracę nad swoim następnym projektem! 😉