Projektowanie dokumentów w ramach Agile

25

W moim miejscu pracy stajemy przed wyzwaniem, ponieważ „zwinność” zbyt często oznacza „niejasne wymagania, złe kryteria akceptacji, powodzenia!”. Staramy się rozwiązać ten problem jako ogólny wysiłek ulepszenia.

W ramach tego proponuję wygenerować dokumenty projektowe, które powyżej poziomu historii użytkownika dokładnie odzwierciedlają wyniki wstępnych badań wpływu danej funkcji w systemie i zawierają odpowiedzi na pytania, które mamy zapytał biznes.

Czy istnieje na to skuteczny standard?

Obecnie mamy do czynienia z sytuacją, w której nowa funkcja może wpływać na wiele obszarów w naszym systemie „wielkiej kuli błota” , a szacunki zaczynają rosnąć z powodu tego długu technicznego. Mamy nadzieję, że bardziej przemyślane procesy projektowania mogą pomóc.

asthasr
źródło
4
zwinnym rozwiązaniem tego problemu jest komunikacja. Osoby odpowiedzialne za poznanie CO powinny być zawsze dostępne dla programistów w celu konsultacji. Ponadto powinieneś mieć testy jednostkowe i częste refaktoryzowanie, aby utrzymać kontrolę nad „dużą kulą błota”.
Euforia
3
Wiem, że powinniśmy mieć te rzeczy. My nie. Próbuję pomóc nam się tam dostać i próbuję ustanowić niezawodne, powtarzalne ramy komunikacji (w końcu dokumenty to komunikacja). Problem polega na tym, że w tej chwili zaczynamy ciężko „zrób to teraz!” cykli, a my polegamy na komunikacji ad hoc, która powoduje, że ludzie mają silosy wiedzy, ponieważ nie ma odniesienia do prawdziwych informacji o funkcji, która pojawia się po historii użytkownika.
asthasr
4
Zwinne nie jest wbrew dokumentacji - jest wbrew zbędnej dokumentacji. Napisz tyle dokumentacji, ile potrzebujesz i nie więcej. W szczególności pamiętaj, że dokumentacja jest tylko odniesieniem do modelu mentalnego, który masz (zespół) w swoich głowach. To drugie jest naprawdę ważne - jednak nie można go w pełni udokumentować. Zamiast tego utrzymuj synchronizację za pomocą dużej ilości komunikacji i zapisz tylko wystarczającą liczbę odwołań, aby zapewnić spójność modelu w perspektywie długoterminowej.
Péter Török
Myślę, że powinieneś zadać inne pytanie niż to. W przypadku tego rodzaju pytań otrzymasz ogólne „dokumenty są w porządku, gdy…”, które nie pomogą ci zbytnio. Powinieneś wiedzieć, czy Twoje rozwiązanie problemu jest prawidłowe i zapytać o inne możliwe rozwiązania.
Euforia
4
„Zwinne nie jest wbrew dokumentacji - jest wbrew bezużytecznej dokumentacji.”: Każdy proces programistyczny jest przeciwny bezużytecznej dokumentacji (zgodnie z definicją użytecznych i bezużytecznych).
Giorgio

Odpowiedzi:

18

„niejasne wymagania, złe kryteria akceptacji, powodzenia!”

tak, to jest ten sam rodzaj wymagań, które masz, nawet jeśli spróbujesz je przygwoździć! (na przykład dokument 10 000 wymagań, którego utworzenie zajęło klientowi rządowemu 4 lata, wciąż był pełen niespójności, niejasności, a nawet wewnętrznie sprzecznych oświadczeń. Jeśli dokumentacja wymagań przez 4 lata nie jest w stanie uzyskać przyzwoitego, dokładnego wymagania, należy zrobić Czy kiedykolwiek myślałeś, że będziesz w stanie uzyskać coś nieokreślonego?)

Więc ... zwinny sposób został wymyślony, aby zrozumieć, że to się dzieje * i pracować z nim, zamiast próbować działać przeciwko niemu.

Zaczynasz od pytania „czego chcesz”, a klient odpowiada „czymś takim”. Wykonujesz trochę pracy, a następnie wracasz do klienta i mówisz „czy to jest to, czego chciałeś?”, A klient zwykle mówi „tak, ale ...”, po czym pytasz „czego chcesz”.

W końcu dostajesz dokładnie to, czego chciał klient, nawet jeśli nie wie, co to jest! (do diabła, nigdy nie wiedzą, czego chcą, niezupełnie).

gbjbaanb
źródło
Ciekawa jest anegdota projektu rządowego, czy jest jakieś źródło? A może po prostu coś, czego doświadczyłeś z pierwszej ręki?
user145400
@ user145400 coś, czego doświadczyłem :-(
gbjbaanb
13

W naszym zespole od czasu zwinności staramy się również zawęzić i zrozumieć, ile dokumentacji jest w rzeczywistości potrzebne. Mogę podzielić się z Tobą tym, czego nauczyliśmy się do tej pory.

Przede wszystkim przeczytaj ten artykuł na temat dokumentacji Agile / Lean . Bardzo dobra lektura.

Po drugie, zdecydowanie doradzam, aby ponownie rozważyć opracowanie dokumentów projektowych po wstępnych pracach nad historiami. Próbowaliśmy tego już wcześniej i okazało się to stratą. W połowie ostatniego wydania postanowiliśmy zaktualizować dokumenty projektowe TYLKO PO dostarczeniu kodu opowiadania. A teraz myślę, że nawet to jest za wcześnie.

Przed kodowaniem musisz zadać sobie pytanie, dlaczego chcesz tworzyć dokumenty projektowe. Dla nas były to powody:

  1. Jako zespół musimy zrozumieć, w jaki sposób historia wpłynie na projekt.
  2. Posiadanie dokumentów projektowych okazało się przydatne, gdy do zespołu dołączają nowi (lub tymczasowi) członkowie lub wracają do kodu, nad którym nikt nie pracował od ponad roku. Są więc przydatne dla pamięci organizacyjnej, aby pomóc zrozumieć, jak działa kod.
  3. Dokumenty projektowe są przydatne dla inżynierów konserwacji, którzy mogą potrzebować rozwiązać problem z kodem po wydaniu.

Aby spełnić (1), nie musisz przedstawiać rzeczywistego dokumentu projektowego. Twój zespół powinien jeszcze mieć fazę projektowania przed kodowaniem, ale ta faza może być tak prosta jak 15 minutowa sesja przed tablicą lub serwetką. Nie musisz tworzyć rzeczywistego dokumentu, którego napisanie zajmie kilka godzin (jeśli nie dni), aby omówić zmiany w projekcie.

(2) lub (3) nie są potrzebne podczas opracowywania bieżącej historii i bardziej niż prawdopodobne, że nie będą potrzebne przez kilka kolejnych iteracji.

Należy również pamiętać, że za każdym razem, gdy członek zespołu pisze / aktualizuje dokumenty projektowe, wtedy ten kod nie jest zapisywany. Kiedy piszesz dokumenty przed faktycznym kodem, istnieje prawie 100% szansa, że ​​będą wymagać aktualizacji, ponieważ po rozpoczęciu kodowania projekt zawsze się zmienia. I nawet jeśli piszesz dokumenty projektowe po kodzie, jak dowiedział się nasz zespół, refaktoryzacja z kolejnych artykułów wciąż zmienia projekt.

Więc co poleciłbym:

  1. Początkowo produkuj tymczasowe projekty / modele na tyle, aby Twój zespół mógł przeprowadzić inteligentną rozmowę przed kodowaniem. Nie oczekuj ich zachowania i nie trać czasu na ich formalizowanie.
  2. Przedstaw oficjalną dokumentację projektową tylko wtedy, gdy ktoś będzie jej potrzebował (tzn. Twój zespół naprawdę potrzebuje pamięci organizacyjnej)
  3. Twórz tylko dokumentację projektową kodu, który został ustabilizowany. Nie ma sensu dokumentować modułu, który zmienia się w każdej iteracji.
  4. Przygotuj dokumenty projektowe, które w pełni opisują moduł (lub część produktu). W przeszłości pisaliśmy dokumenty projektowe, które dokumentowały zmiany, które należy wprowadzić. Dokumenty te były całkowicie bezwartościowe, gdy tylko wydano.
  5. Zachowaj dokument na bardzo wysokim poziomie. Jeśli napiszesz 20 stron o architekturze i bardzo wysokim poziomie projektowania, dokument ten a) zostanie odczytany przez innych ludzi i b) pomoże ludziom zapoznać się z ogólnym układem twojego kodu. Aby uzyskać szczegółowe informacje, ludzie mogą przejść bezpośrednio do kodu. Jeśli napiszesz 700 stron ze szczegółową specyfikacją, prawie zawsze nie będą pasować do rzeczywistości, to jest zbyt wiele do przeczytania i skończysz z utrzymaniem i aktualizacją 700 stron zamiast 20, ilekroć zostaną wprowadzone przyszłe zmiany.
DXM
źródło
To, co mówisz, wydaje się podobne do tego, do czego próbuję dojść; mamy złożoną kulę błota i chcę prostych dokumentów, które: a) przekazują intencje biznesowe dotyczące konkretnej funkcji (tj. opracowane historie użytkowników z odpowiedziami na pytania); b) wskazać, które części kodu i istniejące interfejsy API zostaną zmienione; oraz c) są traktowane jako jednorazowe artefakty, a nie coś, co należy zawsze aktualizować przy każdej nowej funkcji. Mówienie, że 20 stron to „wysoki poziom”, jest dla mnie interesujące - nawet tego jesteśmy pozbawieni. :)
asthasr
@syrion: W oparciu o to, co właśnie powiedziałeś, wygląda na to, że chcesz szczegółowo udokumentować każdą pojedynczą historię i stworzyć dokument „luki projektowej” (tj. określić różnicę między tym, co jest dzisiaj w kodzie, a tym, co będzie w kodzie, gdy tylko historia jest skończona). Czy masz odbiorców takich dokumentów? Z mojego doświadczenia wynika, że ​​nikt tak naprawdę ich nie przeczyta. Programiści pracujący dziś nad historią już wiedzą, co należy zmienić (albo napisali dokument, albo brali udział w początkowej dyskusji). A jeśli spróbujesz uchwycić WSZYSTKIE szczegóły zmian, które zamierzasz wprowadzić w historii, ...
DXM
... poświęcisz więcej czasu na pisanie dokumentacji niż na kodowanie. A kiedy historia się skończy, jak powiedziałeś, są to jednorazowe artefakty. Dlaczego więc przede wszystkim musisz je produkować?
DXM
ponieważ w tej chwili mamy środowisko pełne silosów wiedzy. Mamy ludzi, którzy znają podsystem A, ponieważ go napisali, i B, ponieważ pomogli go wesprzeć, kiedy ostatnio wybuchł, ale nigdy nie dotknęli C i D został przepisany od tego czasu. Początkującym i zewnętrznym kontrahentom trudno jest wejść lub pozostać w pętli.
asthasr
@syrion: to naprawdę brzmi, jakbyś miał taką samą potrzebę, jak my. Jednak zastanawiam się, kiedy powiedziałeś, że potrzebujesz prostych dokumentów, które ... traktowane byłyby jako jednorazowe artefakty. Powiedzmy, że masz warstwę, która mówi do DB i 6 historii, które wymagają zmian w tej warstwie. Czy planujesz wyprodukować 6 różnych dokumentów wraz z każdą historią? A może chcesz mieć jedną specyfikację projektu dla warstwy DB? Jednak pojedyncza specyfikacja musi być aktualizowana przy każdej funkcji dotykającej warstwy DB.
DXM
3

Zwinna „mantra” nie może obejść się bez dokumentacji.

Mantra zwinna woli „ Oprogramowanie działające od obszernej dokumentacji ”. Ale zwróć uwagę na fragment na dole manifestu.

Oznacza to, że chociaż w elementach po prawej stronie znajduje się wartość, bardziej cenimy elementy po lewej stronie ”.

Wujek Bob ma dobrą politykę dotyczącą dokumentacji

Nie okazuj żadnego dokumentu, chyba że jego potrzeba jest natychmiastowa i znacząca .

Masz rację, że niektórzy ludzie używają Agile jako wymówki, aby nie tworzyć dokumentacji, ale to źle Agile. Ignoruje fragmenty, które podkreśliłem w cytatach powyżej.

To powiedziawszy, kiedy mówisz „mamy obecnie do czynienia z sytuacją, w której nowa funkcja może wpływać na wiele obszarów w naszym systemie„ wielkiej kuli błota ”, jeśli chcesz być zwinny, musisz coś z tym zrobić.

Gdy masz dokumentację, użyj jej do modularyzacji kodu. W ten sposób usuwasz długoterminową potrzebę przechowywania dokumentacji (co się nie stanie), usuwając długoterminową potrzebę dokumentacji.

to znaczy. Spraw, aby potrzeba była natychmiastowa i znacząca.

pdr
źródło
Ta odpowiedź jest „poprawna”, ale tak naprawdę nie myśli dalej. Co na przykład z projektem architektury? Co z obrotami programistów / firm? Jak radzi sobie to z wieloma testami jednostkowymi jakości?
Paul,
@Paul: Dobrym pomysłem jest posiadanie BARDZO wysokopoziomowych schematów architektury wraz z bardzo lekkimi standardami kodowania dla początkujących. Przekonałem się, że dobrym sposobem na aktualizowanie tych dokumentów jest utrzymywanie ich na wiki i zachęcanie każdego nowoprzybyłego do aktualizacji tam, gdzie się znajdują. Ale to pytanie dotyczyło przede wszystkim dokumentów projektowych z góry.
pdr
Nadal trzymam się tego, co mówię. Zmień architekturę na coś, co firma chce to nazwać, i zmień testy jednostkowe na testy regresji (zautomatyzowane?) I mają one zastosowanie.
Paul,
@Paul: Przepraszam, nie śledzę. Jak myślisz, jaki cenny dokument jest zły?
pdr
0

Sprawa zwinna polega na tym, że zespół scrum musi naprawdę kierować dokumentacją. Jeśli programiści nie uważają, że zewnętrzna dokumentacja jest wystarczająca dla ich potrzeb, historia użytkownika zostaje zablokowana, dopóki nie zrobią tego. Jeśli firma uważa, że ​​programiści nie tworzą odpowiedniej dokumentacji, właściciel produktu nalega na włączenie jej do kryteriów akceptacji. Z tego powodu odkryłem, że nasza dokumentacja jest bardziej skoncentrowana i skuteczna od czasu przejścia na scrum.

Używamy VersionOne do śledzenia historii użytkowników, ale jestem pewien, że nasze metody dotyczą innych systemów. Pozwala dołączać pliki do historii użytkowników. Odkryliśmy, że jest to niezwykle przydatne miejsce do umieszczania dokumentów projektowych.

W jednym z przykładów, który działał dla nas naprawdę dobrze, musieliśmy przetestować nowy projekt płytki drukowanej tak szybko, jak to możliwe po zbudowaniu prototypu. Stworzyliśmy dwie historie użytkowników dotyczące wszystkiego, co wymagało testowania: jedną do zaprojektowania testu i drugą do wykonania testu. Jednym z kryteriów akceptacji historii projektu było to, że procedura testowa została w pełni udokumentowana w historii wykonania.

Kiedy dotarliśmy do części testowej, poszło gładko, niż kiedykolwiek widziałem. Właśnie otworzyliśmy historię użytkownika i wykonaliśmy procedurę krok po kroku. Dokumentacja była dokładnie tym, czego potrzebowaliśmy, aby ukończyć historię, nie więcej i nie mniej.

W naszym zaległości mamy kolejną historię, aby ulepszyć dokumentację używanego mikroukładu, aby ułatwić innym zespołom wybranie go dla własnych produktów.

Podsumowując, jeśli uważasz, że twoja dokumentacja cierpi, rozwiązanie jest tak proste, jak stworzenie dla niej osobnej historii użytkownika i / lub włączenie jej do kryteriów akceptacji.

Karl Bielefeldt
źródło
0

Kiedy mówisz o złych wymaganiach, pierwszą rzeczą, która przychodzi mi na myśl, jest upewnienie się, że masz kryteria testowe. Jeśli to możliwe, stwórz kilka automatycznych przypadków testowych wielokrotnego użytku dla istniejących części systemu. Gdy wszyscy poczują się dobrze, przejdź do pisania przypadków testowych przed napisaniem kodu. Dobre przypadki testowe mogą wiele zrobić, aby udokumentować zachowania systemu.

Co do tego, jakich konkretnych dokumentów projektowych użyć, jak już powiedzieli inni, jest wysoce zależne od potrzeb zespołu i od tego, jakie będzie następne zadanie. Jeśli to możliwe, spróbuj użyć narzędzi, które mogą generować dokumenty (z kodu), których chcesz użyć, lub wygenerować kod z dokumentu. Utrzymanie dokumentacji może stać się dość drogie, więc wybieraj mądrze, gdy zachowasz dokument projektowy.

Osobiście miałem dobry sukces ze schematami klas wygenerowanymi z kodu i przypadków testowych fitnesse. Zespół drukuje kilka diagramów klas, przeprowadza sesję narzutu z właścicielem produktu, a następnie formułuje szacunek na jego podstawie. Jeśli chodzi o fitnesse, mam szczęście współpracować z kilkoma właścicielami produktów, którzy bardzo dobrze wyrażają to, czego chcą w arkuszach kalkulacyjnych, które są następnie konwertowane na tabele dla fitnesse.

Klasa abstrakcyjna
źródło