Określenie odpowiedniej ilości dokumentacji

Tam, gdzie obecnie pracuję, ogólne podejście to:

unikaj dokumentacji w jak największym stopniu

Dokumentuj tylko, jeśli inny zespół będzie go potrzebował

tylko dla wyjaśnienia, nie chodzi mi o dokumentację kodu - chodzi o całą dokumentację związaną z procesem projektowania - jeśli są to schematy UML lub DB, diagramy klas i dokumenty słowne ze specyfikacjami i podobnymi.

Wymienię powód mojego szefa, by nie dokumentować:

1. jest czasochłonne - skup się na wdrażaniu
2. jeśli zmiana projektu - to dokumentacja powinna się zmienić, podwójny problem
3. w końcu dostajesz tylko setki stron, których nikt nie chce czytać, i nikt tak naprawdę nie edytuje, więc z czasem to się zmieni
4. To ból - nikt tak naprawdę nie chce tego robić

Teraz zdaję sobie sprawę, że pracujemy szybciej, ale pamiętam też czas, kiedy tu dotarłem i nurkowałem prosto do starego kodu, niczego nie rozumiejąc.

W rzeczywistości nadal nie otrzymuję większości tego starego kodu, a czasami po wejściu widzę wiele łatek od różnych programistów próbujących wprowadzić drobne poprawki.

Naprawdę uważam, że brak dokumentacji promuje tego rodzaju łatki i brak zrozumienia systemu w szerokim znaczeniu.

moje pytanie brzmi:

W jaki sposób możemy zrównoważyć dokumentację, aby promować stałą wiedzę wśród zespołu, a jednocześnie być szybkim i wydajnym?

Odkryłem, ŻADNA dokumentacja jest lepsza niż BRAK dokumentacji. Odpowiednia ilość jest zwykle określana przez czas, jaki musimy to zrobić, lub przez to, jak bardzo nienawidzimy obsługi połączeń telefonicznych i e-maili.

Wygląda na to, że twoi obecni członkowie zespołu mają pewne nierealistyczne oczekiwania wobec swoich wspomnień lub wstydzą się swoich umiejętności pisania i nie chcą ćwiczyć.

Zdaję sobie sprawę, że jestem w mniejszości (angielski, który rozpoczął studia inżynierskie w szkole wyższej), ponieważ nie uważam dokumentacji za obowiązek. To cenne profesjonalne narzędzie. Pisanie może być dla mnie trudniejsze niż niektórych moich współpracowników, ale dzieje się tak głównie dlatego, że mam w tym więcej praktyki. Nie uważam projektu za skończony, chyba że ma dokumentację, i zwykle piszę go z czysto egoistycznych powodów: dlatego mogę dać ludziom coś do przeczytania zamiast odbierać telefony i e-maile, lub żeby zapamiętać, o czym rozmawialiśmy ostatnio mniej więcej miesiąc mogę odnieść się do tego, jak coś zrobiłem, jeśli muszę to wesprzeć w środku nocy.

Najlepszym sposobem na zbliżenie się do dokumentacji jest napisanie jej JAK TYLKO, dokładnie tak jak pisanie kodu testowego. To niesamowite, jak kilka gotowych szablonów (z nagłówkami, fragmentami kodu itp.) Może ułatwić i przyspieszyć tworzenie dokumentacji. W ten sposób możesz uchwycić zmiany, które się zdarzają, i masz mniej przestrzeni do pokrycia w czasie. W ten sposób jesteś bardziej wydajny, ponieważ możesz odwoływać się do potrzebnej dokumentacji i zmieniasz ją po drodze. Robiąc to na przykład na wiki, ułatwia aktualizację i możesz uniknąć problemów z wersją dokumentu, jeśli najnowsze i najlepsze są zawsze dostępne online w tym samym miejscu, i możesz po prostu wysyłać linki do osób, które muszą je przeczytać.

Jeśli poświęcisz trochę czasu na dokumentowanie, WSZYSTKO będzie działać szybciej, szczególnie gdy ktoś nowy dołączy do zespołu, ponieważ nie będzie musiał spędzać całego czasu na rozpracowywaniu wszystkiego. Odkrywanie rzeczy jest fajną częścią naszych zadań, ale nie jest fajne, gdy trzeba to robić w pośpiechu, aby naprawić produkcję. Wszyscy zaoszczędzilibyśmy dużo czasu, gdybyśmy wszyscy napisali jeszcze kilka notatek.

Czy Twój zespół ma takie same problemy z testowaniem lub pisaniem kodu testowego? Jeśli nie, będzie to łatwiejsza sprzedaż.

Twoja dokumentacja jest przydatna na wiele sposobów:
1) Dla ciebie, teraz i dla twoich współpracowników, podczas pracy nad projektem.

2) Do twoich klientów. Posiadanie dokumentacji (w tym diagramów), którą można pokazać użytkownikom, ułatwia dyskusje na spotkaniach, zwłaszcza jeśli omawia się skomplikowane systemy. Nawet jeśli dokumentacja jest niekompletna, warto zacząć od niej.

3) Do ludzi, którzy odziedziczą twoją pracę (którym może być ty, za trzy lata). Wielu moich młodszych współpracowników uważa, że ​​zapamiętają rzeczy na zawsze. Wiem, że nie zapamiętam tego w tym tygodniu, jeśli tego nie zapiszę. Posiadanie dokumentacji pozwala uniknąć konieczności spędzania pół dnia na pamiętaniu, jak coś ustrukturyzowałeś, i konieczności ponownego rozpracowywania tego wszystkiego.

4) Tobie i innym, jeśli sytuacja stanie się polityczna lub kontrowersyjna. Jako ktoś, kto robi notatki na spotkaniach, aby nie zasnąć i walczyć z nudą, często byłem jedynym, który napisał wersję decyzji. Osoba, która go zapisała, wygrywa spór. Pamiętasz to następnym razem, gdy ktoś mówi: „Pamiętasz to spotkanie, które mieliśmy zeszłej zimy w sali konferencyjnej 4, kiedy jechaliśmy nad X? Fred tam był i kim jest ten facet z księgowości?”

U kilku moich ostatnich pracodawców mieliśmy wiki „rozwoju”. Dokumentuje się tam znaczące fragmenty funkcjonalności (nowy plik danych importu / eksportu, sposób działania podsystemu bezpieczeństwa, gdzie system przechowuje przesłane dokumenty itp.). Zazwyczaj jest to element obowiązkowy do wypełnienia przed krokiem przeglądu kodu. Na początku jest na to trochę oporu, ale gdy ktoś musi poszukać trochę informacji i już tam jest, masz kolejną konwersję.

Zaletą posiadania go w formacie wiki jest to, że jesteś o wiele mniej skłonny do wykonywania ładnego formatowania Worda i po prostu zapisywania prawdziwych informacji, które musisz zapisać. Większość (jeśli nie wszystkie) pakiety wiki pozwalają na przesyłanie dokumentów lub obrazów (takich jak diagramy UML programu Visio lub szkielety interfejsu użytkownika), więc możesz mieć także elementy wizualne.

Podobnie jak większość rzeczy, myślę, że powinieneś dążyć do zrobienia minimalnej kwoty, która mogłaby ewentualnie działać. To jednak nie to samo, co żadne.

Nie można uniknąć przydzielania czasu na napisanie odpowiedniej dokumentacji. Zrównoważyć to, ile chcesz, w zależności od tego, ile pracy dostaniesz, ale zostaw 15-20% swojego czasu na udokumentowanie swojej pracy. Wszyscy w zespole muszą być przy tym zaangażowani, w tym Twój kierownik, w przeciwnym razie będziesz dokumentować tylko na korzyść innych i nie dostaniesz nic w zamian. Dokumentacja musi stanowić integralną część procesu rozwoju.

Dokumentacja powinna informować, DLACZEGO coś zrobiłeś, pozostawiając część HOW rzeczywistemu kodowi, a CO część testom jednostkowym. Coś więcej to ból. Jest to zwykle wystarczające dla inteligentnych ludzi, którzy chcą tylko punktu wyjścia.

Nie zapomnij również o utrzymaniu ogólnej architektury wysokiego poziomu każdego dużego komponentu bazy kodu. Ułatwia wprowadzenie nowych członków zespołu.

Wreszcie, za każdym razem, gdy dodajesz dziwną poprawkę, link do bazy danych błędów z komentarza - bardzo przydatny.

Twój szef ma rację, nie drukuj żadnej dokumentacji UML, której nikt nie przeczyta. W naszym zespole nawigujemy na żywo w modelu za pomocą widoków diagramów klas. Zasadą jest, aby zawsze aktualizować MOF, model UML na żywo z kodu i pozwolić, aby diagram klas był tylko przeglądarką modelu, ale nie samym modelem.

Działa naprawdę dobrze, ponieważ cała złożoność odbywa się w backoffice na poziomie modelu. Mogę refaktoryzować mój projekt, napisać dokumentację Java lub napisać dokumentację uml w modelu. Jest to rodzaj „kliknij i idź”. Po kliknięciu otrzymasz dokumentację na żywo. Jeśli coś nie jest jasne, otwieram diagram klas i zaczynam się nim bawić. Usuń z klasyfikatorów diagramów, dodaj nowe klasyfikatory, powiększaj i pomniejszaj, pokaż powiązanie, usuń powiązanie itp. Model nie został zmieniony, ponieważ nie tworzę żadnych nowych informacji o modelu, po prostu ich używam.

Naprawdę ważne jest, aby otworzyć diagram pakietu i móc przeczytać bezpośrednio na diagramie klasy komentarz na temat tego, czym powinna być ta klasa. Co ta metoda ma zrobić i jaki jest przepływ itp ...

UML jest świetny, naprawdę pomocny, ale powinniśmy zaprzestać korzystania z rozwoju opartego na modelu, aby zapewnić większą elastyczność i więcej iteracji na etapach modelowania / rozwoju. Diagram klas jest na bieżąco aktualizowany z kodu, a dokumentacja jest zawsze dokładna i dostępna tylko jednym kliknięciem. Nie wspomnę o narzędziu, ale jeśli używasz Java i Eclipse, łatwo jest znaleźć narzędzie, którego używam :-)