Jaki jest skuteczny sposób rejestrowania uzasadnienia decyzji dotyczących projektu produktu?

W naszej firmie nie korzystamy z żadnych dokumentów projektowych produktu. Mamy łącznie trzech pracowników, więc wszystkie dyskusje na temat projektu produktu odbywają się osobiście lub w serwisie Slack. (Jesteśmy również na podstawowym pakiecie Slack, który pozwala tylko przeglądać najnowsze wiadomości.)

Nasz produkt jest wciąż na wczesnym etapie i często ponownie odwiedzamy elementy projektu, o których zdecydowano kilka miesięcy temu.

Problemem, z którym często mamy do czynienia, jest zapominanie, dlaczego podjęto decyzję dotyczącą projektu produktu. Powoduje to zmarnowane godziny bieżnikowania tego samego podłoża.

Jak możemy skutecznie rejestrować uzasadnienia decyzji projektowych?

Nasz obieg pracy oparty jest na Pivotal Tracker. Jednym z rozwiązań, które przychodzi mi do głowy, jest rejestrowanie uzasadnienia wszystkich istotnych decyzji projektowych jako komentarzy do samej historii użytkownika, ale wydaje się to niewiarygodne.

Żeby być w 100% jasne: nie mówię o projekcie kodu. Mówię o projekcie produktu realizowanym przez kod. Innymi słowy, nie mówię o decyzjach typu „czy powinniśmy ustrukturyzować tę klasę przy użyciu kompozycji, a nie wielokrotnego dziedziczenia?”; Mówię o takich decyzjach, jak „czy powinniśmy wymagać od użytkownika potwierdzenia adresu e-mail przed zalogowaniem się?”.

Dokumentacja ma na celu umożliwienie firmie przejrzenie rejestru, dlaczego podjęto decyzje, aby pomóc w podjęciu dalszych decyzji dotyczących tych samych tematów.

Zapisujesz uzasadnienia decyzji projektowych, zapisując je. Idealnie blisko przedmiotu podlegającego decyzji (który nie jest „historią użytkownika” - historie użytkownika to opisy tego, co należy wdrożyć, a nie jak).

Do tego właśnie służą komentarze - aby rejestrować, dlaczego tak wygląda określony fragment kodu lub struktura (i nie mówię wyłącznie o komentarzach do kodu). Jeśli przedmiotem twojego projektu jest funkcja, zrób komentarz wprowadzający do tej funkcji. Jeśli jest to klasa, zrób komentarz na początku klasy na temat uzasadnienia. Jeśli masz kilka klas, które powinny mieć tę samą strukturę, dodaj osobny dokument projektowy (np. Plik „readme”) do pakietu zawierającego te klasy. Jeśli przedmiotem twojego projektu jest diagram UML, dodaj komentarze do sekcji opisu diagramu.

Dokumenty projektowe IMHO mogą mieć swoją wartość, ale jeśli opisują rzeczy zbyt „daleko” od opisywanego przedmiotu, bardzo szybko stają się niespójne. Dlatego zalecam umieszczenie dokumentacji projektowej jak najbliżej projektowanego elementu.

Używaj osobnych dokumentów tylko wtedy, gdy chcesz dokumentować decyzje projektowe, które wpływają na wiele różnych miejsc kodu w sposób przekrojowy. Kiedy ich używasz, staraj się, aby były częścią bazy kodu i umieść je na odpowiednim poziomie hierarchii projektowanego przedmiotu (więc jeśli podejmiesz decyzję projektową dla jednego modułu, który składa się z wielu plików kodu źródłowego, umieść opis projektu „ wewnątrz „tego modułu, ale nie w jednym pliku klasy, nie w„ opisie najwyższego poziomu ”, który jest ważny dla innych modułów, a na pewno nie w oddzielnej Wiki poza SCCS. Jeśli chcesz nagrać jakiś„ wysoki poziom ”, produkt szerokie decyzje projektowe, a następnie dokument najwyższego poziomu może być najlepszym miejscem, ale upewnij się, że ten dokument pozostaje na tym poziomie abstrakcji.

Rozważ zwinne podejście. Mam na myśli, jeśli masz zasoby czasu i doskonałe umiejętności pisania, aby zapisać każdą decyzję dotyczącą projektu wraz z uzasadnieniem, po prostu udokumentuj wszystko. Mówiąc realistycznie, zakładam, że nie jesteś w takiej sytuacji. Podejście zwinne może pomóc w kluczowym wyzwaniu związanym z dokumentacją uzasadnień: często nie wiesz, które uzasadnienia były ważne do czasu późniejszego.

Podejdźmy do problemu z holistycznego punktu widzenia. Masz uzasadnienie swojej decyzji. Są teraz uwięzieni w kruchym oprogramowaniu, mózgach zespołu. Pomimo ilości dokumentacji kredytowej, przechowywanie uzasadnień w oprogramowaniu sqishyware nie jest wcale takie złe. Jesteśmy naprawdę dobrzy jako gatunek w zapamiętywaniu ważnych rzeczy. To dlatego każda duża korporacja ma „wiedzę plemienną”, nawet gdy korporacje starają się udokumentować całą tę wiedzę plemienną.

Teraz masz problem. Stwierdzasz, że oprogramowanie sqiushyware nie trzyma się wystarczająco uzasadnionych przesłanek. Dobrze, że zdajesz sobie sprawę, że jest problem i że musisz go rozwiązać! To nie zawsze jest łatwy krok! Jesteśmy więc prawie pewni, że rozwiązaniem jest przeniesienie części tego uzasadnienia do dokumentacji. To jednak nie wystarczy. Nigdy nie możemy zapomnieć drugiej połowy układanki, która polega na ponownym załadowaniu uzasadnienia do oprogramowania typu squishyware, gdy trzeba podjąć decyzję. Widziałem wiele zespołów, które dokumentują wszystko jak szalone, ale treść nie jest tak zorganizowana, aby pomagać w podejmowaniu dobrych decyzji, więc ostatecznie zapominają o uzasadnieniu, nawet jeśli są spisane .

Więc masz dwuetapowy proces. Musisz wydobyć uzasadnienie ze squishyware do dokumentacji. Następnie musisz upewnić się, że dokumentacja jest wystarczająco dobrze zorganizowana, aby w razie potrzeby przywrócić racjonalność do squishyware! Teraz myślę, że mamy wystarczająco dużo opisów problemów, aby zdać sobie sprawę z tego, jakie wyzwania będą lubić. Kiedy dokumentujesz, zwykle nie wiesz, kto będzie na to patrzył później ani czego oni szukają. Podobnie, gdy przeglądasz dokumentację, zwykle nie wiesz, czego szukasz (w najlepszym razie możesz wiedzieć, kiedy).

Tak więc duża firma może spróbować poradzić sobie z tym w dwóch dużych blokach. Najpierw mogą opracować wymagania w oparciu o to, czego ludzie potrzebują podczas badania dokumentacji. Następnie wykorzystują te wymagania, aby zbudować proces opracowywania wspomnianej dokumentacji. A jeśli ośmielę się to powiedzieć, wszyscy narzekają, ponieważ prawie nikt nie wie dokładnie, jak powinna wyglądać dokumentacja pierwszego dnia. Dokumentacja jest zawsze niekompletna, a programiści zawsze narzekają, że proces jest zbyt uciążliwy.

Czas na zwinność.

Moją radą byłoby rozpoczęcie zwinnego wysiłku w celu ulepszenia procesu dokumentacji: całe dziewięć jardów od squishyware do dokumentu i z powrotem do squishyware. Rozpoznaj z góry, że stracisz trochę informacji, ponieważ twój proces nie jest doskonały, ale to w porządku, ponieważ wciąż próbujesz rozgryźć proces! Tęskniłbyś więcej, gdybyś próbował stworzyć jeden rozmiar dla wszystkich rozwiązań.

Kilka szczególnych ciekawostek, na które chciałbym spojrzeć: * Przeglądaj nieformalną dokumentację. Formalna dokumentacja jest świetna, ale zajmuje dużo czasu. Jednym z celów dokumentacji jest udostępnianie informacji od twórców oprogramowania typu squishyware i umieszczanie ich na papierze. Nieformalna dokumentacja ogranicza koszty do minimum.

• Akceptuj niewiarygodne formaty dokumentacji. Za pierwszym razem nic nie będzie dobrze. Lepiej jest uzyskać dane i dowiedzieć się, jak uczynić je później wiarygodnym. Na przykład możesz udokumentować swoje uzasadnienia w bloku <rationale> </rationale> lub w podobnym celu, co ułatwiłoby później pozyskanie tych danych. Przechowywanie uzasadnień w historii użytkownika jest na razie w porządku!
• Nigdy nie zapominaj o wartości organizacji. Dowiedz się, w jaki sposób Ty, jako zespół, lubisz szukać uzasadnienia w dokumentacji i spróbuj udokumentować to. Każdy zespół będzie miał inny proces. W jednym z moich zespołów nigdy nie znaleźliśmy biletu, który miałby uzasadnienie. Co możemy zrobić, to znaleźć wiersz kodu, który ma znaczenie, zrób, svn blameaby dowiedzieć się, kiedy się zmienił i dlaczego, a następnie spójrz na bilety. Gdy już tam byliśmy, zwykle umieszczaliśmy wszystkie uzasadnienia, których potrzebowaliśmy, bezpośrednio na bilecie. To właśnie dla nas zadziałało, dowiedz się, co działa dla Ciebie.
• Dokumentacja organiczna może z czasem rosnąć. Programiści rzadko wiedzą, które uzasadnienia są najważniejsze w dniu, w którym musieli je napisać. Zazwyczaj dowiadujemy się, które z nich były ważne później. Jeśli masz proces przygotowywania dokumentacji, który pozwala programistom zarządzać własnym ogrodem z uzasadnieniami, ważne z nich wyjdą na powierzchnię. Co ważniejsze, uzasadnienia mogą ulec zmianie. Być może zdajesz sobie sprawę, że dwie różne zmiany, z dwoma różnymi uzasadnieniami, naprawdę najlepiej można opisać za pomocą jednego uzasadnienia, które działa dla obu. Teraz między Tobą a decyzjami jest mniej treści!

Sugeruję utworzenie prywatnej instancji MediaWiki lub podobnego oprogramowania wiki. Naprawdę łatwo jest tam organizować i reorganizować treści, a nowe dyskusje można kopiować i wklejać bezpośrednio na karcie dyskusji odpowiednich artykułów na wiki. Użyliśmy MediaWiki w mojej ostatniej pracy dla wszystkich naszych dokumentów architektury i API, i to uratowało życie.

Pomyśl o tym z punktu widzenia kodera, który zostanie poproszony o zmianę za 12 miesięcy.

Jeśli dodasz tę regułę biznesową jako test automatyczny, zmiana zostanie wprowadzona, A NASTĘPNIE uzyskasz niespełniony test sprzecznego wymogu (i mam nadzieję, że schwytasz osobę związaną z pierwotnym wymaganiem i powód jego podania).

Uważam dokument projektowy (miejsce, w którym umieszczasz diagramy BPMN, diagramy transakcji, a nawet zdjęcie tablicy itp.) Jako podobne do kodu, po prostu niewykonalny formularz ... co oznacza to, co próbujesz rekord jest podobny do komentarza do kodu, ale wymaganie (testowalne) określone z góry w projekcie. Prawdopodobnie jeśli jesteś zwinnym sklepem, nadal projektujesz swój kod, po prostu robisz to w ostatniej chwili przed jego napisaniem. Zachowaj to w bazie kodu ze wszystkimi innymi dokumentami projektu.

Cokolwiek zrobisz, upewnij się, że jest przechowywane w sposób umożliwiający wyszukiwanie (na przykład możesz chcieć wyciągnąć wszystkie reguły biznesowe związane z „uwierzytelnianiem” podczas określania nowych zmian).

Jak zawsze, gdy coś piszesz, musisz zadać sobie pytanie, kim są docelowi odbiorcy. Mocno wierzę, że dokumenty projektowe są dostępne dla moich programistów, obecnych lub przyszłych. Dokument pomaga im zrozumieć, co buduję lub co zostało zbudowane (ogólny przegląd) i, co ważniejsze, dlaczego. Jest to miejsce do udokumentowania rozważanych alternatyw, zalet i wad każdego z nich.

Mówiąc, że jest w porządku, aby jakiś projekt mógł żyć w ludzkich mózgach, pomija się, że programiści idą dalej i znajdują różne prace, zabierając ze sobą te cenne informacje.

Posiadanie kodu jako jedynej dokumentacji projektowej jest jak poruszanie się po mieście za pomocą szkła powiększającego. Mapa jest o wiele bardziej przydatna (niestety nie ma odpowiednika GPS dla kodu źródłowego).

Zgadzam się, że dokumentacja projektowa gnije nawet szybciej niż kod. A ponieważ nie jest możliwa żadna walidacja między nimi, jedyne, co możesz zrobić, to trzymać je blisko siebie. IMO, datowany dokument projektowy nadal dostarcza cennych informacji.