Czy dokument projektowy powinien zawierać omówienie zalet / wad danego projektu, czy powinien koncentrować się na faktach i uzasadnieniu?

Obecnie jestem w trakcie aktualizacji dokumentu projektowego, aby był poprawny i aktualny dla przyszłych programistów.

Obecnie dokument koncentruje się tylko na faktach, przedstawiając projekt. Nie ma uzasadnienia dla jakichkolwiek przedstawionych decyzji. Uważam, że ważne jest uchwycenie uzasadnienia, aby programiści wiedzieli, dlaczego coś takiego jest, ponieważ prawdopodobnie wpłynie to na przyszłe decyzje. Nie mogę dodać uzasadnienia dla wszystkich decyzji projektowych, szczególnie tych, które zostały podjęte przed rozpoczęciem pracy nad projektem, ale robię, co mogę w tym dziale.

Jednak niektóre decyzje projektowe są, z szacunkiem, bardzo złymi decyzjami, biorąc pod uwagę wymagania projektu. Ale są też dobre.

Początkowo myślałem, że powinienem omówić problemy projektowe i potencjalne rozwiązania lub obejścia tych problemów, aby zwrócić uwagę przyszłych opiekunów, ale nie jestem pewien, czy dokument projektowy jest miejscem dla tego rodzaju dyskusji i informacji. Nie chcę, aby „krytyka” projektu zmieniła się w „zgrywanie tego projektu na nowy”, ponieważ inni ludzie pracują w tym systemie i aktualizują dokument, ponieważ jest to wyraźnie nieodpowiednie.

Mój kierownik poparłby każdą decyzję, więc to zależy ode mnie. Niezależnie od przyjętego przeze mnie podejścia opracowany dokument byłby oficjalnie wersjonowany i udostępniany programistom pracującym w systemie, zwykle przed zleceniem pracy programistycznej. Oczekuje się, że nowy programista zapozna się z dokumentami związanymi z danym systemem oprogramowania przed rozpoczęciem prac programistycznych.

Pytania:

• Czy dokument projektowy powinien trzymać się surowych faktów („to jest projekt”) i uzasadnienia („oto dlaczego jest to projekt”), czy też powinien zostać wykorzystany do wskazania nie wadliwych problemów z projektem, które mogą być problematyczne dla przyszli programiści?
• Jeśli dokument projektowy nie powinien być używany do przechwytywania tych informacji, jaki typ dokumentu powinien je przechwycić, a co jeszcze należy uchwycić, omawiając uzasadnienie projektu, kompromisy i znane problemy (które nie są wadami, ponieważ wady są śledzone używasz innych narzędzi)?

Jeśli zalety i wady można streścić w zdaniu lub dwóch, to dobrze jest umieścić je w dokumencie projektowym. Coś już należy oddzielić.

Tam, gdzie obecnie pracuję, zwykle jest osobny dokument „Decyzje projektowe”, aby śledzić wszystkie ważne i ważne decyzje. Często sformatowane w akapicie opisującym problem (np. „Niektóre pliki muszą zostać przeniesione z serwera do określonych użytkowników na koniec każdego cyklu przetwarzania, istnieje wiele sposobów aby to zrobić ...”), tabela z kolumnami ” opis rozwiązania ”(np.„ przenieś pliki przez FTP ”),„ profesjonaliści ”(np.„ Łatwy w zarządzaniu dla użytkowników ”),„ wady ”(np.„ niewystarczająco bezpieczny dla zgodności z ABC-XYZ ”) i wniosek, że wyjaśnia, dlaczego wybrano określoną decyzję (np. „FTP nie będzie używany, ponieważ nie będzie w stanie spełnić pewnych wymagań zgodności”). Dokument projektowy zwykle odnosi się tylko do wybranej decyzji,

Czy dokument projektowy powinien trzymać się surowych faktów („to jest projekt”) i uzasadnienia („oto dlaczego jest to projekt”), czy też powinien zostać wykorzystany do wskazania nie wadliwych problemów z projektem, które mogą być problematyczne dla przyszli programiści?

To nie jest „albo-albo”.

Przede wszystkim nikt nie czyta dokumentacji. Prześlizgują się - w najlepszym razie. Dlatego napisz jak najmniej dokumentów. Jeden dokument to wszystko, na co każdy ma cierpliwość. Drugi dokument „non-desgin” z „innymi problemami” w ogóle nie zostanie odczytany.

Zalety jednego dokumentu? Ludzie mogą to przeczytać.

Wady jednego dokumentu? Mało. Przeważnie staje się nieaktualny.

Zalety wielu dokumentów? Żaden.

Wady wielu dokumentów? Przeczytaj zasady DRY i umieć pisać. Wiele dokumentów oznacza wiele źródeł błędów. Każdy dokument nie zgadza się z drugim i nie zgadza się z kodem. To całkiem oczywiste. To jest ścieżka szaleństwa.

Unikaj załamywania rąk.

Dokument za i przeciw może przeciągać się w nieskończoną głębię dyskusji o atrakcyjnych i uciążliwych dyskusjach.

Jeśli uważasz, że konieczne jest przedstawienie plusów i minusów, krótko i na temat.

Skoncentruj się na tym, co jest.

Trzymaj to, co nie jest do gołych kości.

Jeśli wykonałeś testy porównawcze, badania lub faktycznie zbadałeś alternatywy, udokumentuj to. Ale jeśli zastanawiasz się nad alternatywami, zminimalizuj je.

To nie powinna być twoja osobista historia procesu i ucisku.

• Miałeś problem? Naprawione? Zajęło Ci tygodnie? Naprawdę walczyłeś? Ciekawa anegdota. Jest to ustalone w kodzie. Poprzednie wersje, złe wersje, błędne wersje i wersje o niskiej wydajności nie mają znaczenia. W najlepszym razie są to pokarmy dla blogów.

• Nadal masz problem? Nie naprawiony? Oznacza to, że istnieją alternatywy. Dokumentuj to.

Istnieją 3 ważne fakty w procesie podejmowania decyzji:

• Co zostało wypróbowane i nie działało (i dlaczego nie działało, ponieważ celujesz w ruchomy cel)
• Co jest
• Co może być (tylko czekam na wdrożenie X ...)

Jednak oprócz „Co to jest”, wszystkie inne wprowadzą czytelnika w błąd i zapobiegną zabrudzeniu systemu.

Podoba mi się pomysł przechwycenia pozostałych 2, chociaż są one mniej interesujące do nauki systemu, mogą oszczędzać czas podczas jego zmiany.

Dlatego chciałbym rozwinąć pomysł odsłonięty @FrustratedWithFormsDesigner z niespodzianką. Zamiast tworzyć kolejny dokument z własnym cyklem życia, chciałbym skreślić załącznik. Następnie dla każdej decyzji wartej dyskusji wskazałbym odpowiedni wpis w załączniku.

Tak. Dokument projektowy powinien wyjaśniać korzyści, ryzyko i założenia związane z opisywanym projektem. Dokument projektowy ma kilka celów:

1. Zapisz projekt, aby wszyscy go zrozumieli i aby zrozumienie każdej osoby nie dryfowało w czasie.

2. Przekazuj projekt nietechnicznym osobom pracującym nad projektem.

3. Pomoc w planowaniu, alokacji zasobów, szacowaniu kosztów i innych rodzajach planowania.

4. Staje się ważną częścią ogólnej dokumentacji projektu. Gdy dołączasz do projektu w toku lub musisz utrzymać ukończony, życie jest o wiele łatwiejsze, jeśli istnieje dobrze napisany dokument projektowy.

5. Jest często jednym z rezultatów wymaganych umową.

(Prawdopodobnie są inne, ale to dobry początek.)

Każdy z tych celów jest dobrze obsługiwany przez dokument projektowy, który jasno wyjaśnia, dlaczego wybrano ten projekt i jakie są związane z tym zagrożenia:

1. Ważne jest, aby wszyscy członkowie zespołu wiedzieli, jakie są ryzyka i korzyści, aby mogli współpracować w celu uniknięcia tych zagrożeń i jak najlepszego wykorzystania korzyści płynących z projektu.

2. Dla nietechnicznych członków zespołu zrozumienie ryzyka i korzyści jest często ważniejsze niż szczegóły samego projektu.

3. Zarządzanie ryzykiem jest jedną z najważniejszych rzeczy, które kierownik projektu może zrobić, aby zapewnić sukces, a pierwszym krokiem jest określenie ryzyka, którym należy zarządzać. Decyzja o tym, jak radzić sobie z ryzykiem, powinna należeć do kierownika, ale to do projektanta należy wskazanie znanych zagrożeń związanych z projektem.

4. Nawet gdy ryzyko nie stanowi już problemu, często warto je udokumentować, ponieważ może to pomóc w wyjaśnieniu sytuacji w momencie tworzenia projektu. To może pozwolić opiekunowi podjąć decyzję w rodzaju: „OK, zrobili to wtedy, ponieważ ... ale to już nie jest problem, więc mogę zastąpić ten kod prostszą, szybszą implementacją”. To samo dotyczy korzyści.

5. Jeśli pracujesz nad projektem dla klienta, szczególnie ważne jest udokumentowanie ryzyka i korzyści. To powoduje, że klient jest powiadamiany, że w pewnych okolicznościach może dojść do awarii lub że żądanie zmian w projekcie może zagrozić niektórym obiecanym korzyściom.

Wywodzę się z pytania, że ​​pracujesz z istniejącym dokumentem projektowym dla systemu, który został już zaimplementowany. W takim przypadku wiele możliwych zagrożeń nie jest już ryzykami, więc nie ma sensu próbować ich dokumentować po fakcie. Jednak teraz masz przewagę z perspektywy czasu, ponieważ możesz zobaczyć części oryginalnego projektu, które nie zadziałały tak dobrze. Myślę, że powinieneś: dodać oddzielną sekcję, która identyfikuje aktualne obszary problemowe i proponuje rozwiązania (w tym związane z nimi ryzyko!); lub utwórz osobny dokument, który robi to samo. Ta nowa sekcja / dokument może przekształcić się w dokument projektowy dla następnej wersji oprogramowania.

Oto wpis na blogu dotyczący pisania dokumentów projektowych , które mogą okazać się pomocne.

Jeśli istnieją uzasadnione powody, by unikać bardziej oczywistych lub standardowych rozwiązań, należy je odnotować. Zaoszczędzisz komuś dużo kłopotów. Jednak określona technologia może z czasem ulec poprawie, więc Twoje powody mogą nie mieć zastosowania. Przyszły programista może następnie użyć własnego osądu.

Nie wiem, czy wskazanie wszystkich niedociągnięć przynosi wiele korzyści. Wprowadzanie zmian lub innych priorytetów może być niepraktyczne. Możesz naprawić niektóre z nich w najbliższej przyszłości, a będzie to tylko jedna rzecz do zaktualizowania.

Osobiście nie umieszczałbym tego w dokumencie projektowym. Dokument projektowy powinien określać, jak to jest, a nie dlaczego.

Jeśli uważasz, że istnieje potrzeba przedstawienia historii, dlaczego projekt jest taki, jaki jest, być może powinieneś umieścić to w artykule na wiki (lub jakiejkolwiek bazie wiedzy, z której korzysta Twoja firma), aby można było zapoznać się z historią ewolucja projektu. Ludzie mogą go czytać, edytować i dodawać sugestie. W ten sposób jest to bardziej otwarta dyskusja zamiast brwi w dokumencie.

Zgadzam się z tobą w sprawie uzasadnienia w dokumencie projektowym.

Tak czy siak,

podczas aktualizacji dokumentu projektowego napisanego przez kogoś innego pozostałbym pokorny i nie próbowałbym zgadnąć, dlaczego podjęto taką decyzję.

Więc,

Wstawiłbym uzasadnienie tylko o zmianach wprowadzonych w projekcie podczas konserwacji.