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!