Jak planujecie/dokumentujecie pet projects/zlecenia po godzinach.

Może głupie pytanie, ale często mam tak, że gdy zaczynam jakiś pet project/project pisany do klienta "po godzinach" to fazę projektową mocno skracam i siadam do kodowania - w trakcie pomysł ewoluuje - normalnie projekt 110% agile ;)

W pracy to wiadomo - faza planowania, sporządzanie dokumentacji funkcjonalnej, 5 ton makulatury itd. No ale wiadomo jest wielu devów, trzeba zaplanować budżet, spisać co my dokładnie chcemy zrobić, żeby klient się pod tym podpisał i potem się nie dziwił, że czegoś nie ma.

Chciałbym znaleźć jakiś złoty środek między tymi podejściami dla projektów powiedzmy na 2-3 miesiące klepania po godzinach, żeby coś tam zostało na papierze, aby po czasie można bylo się do tego odwołać, żeby było to w miarę łatwe do zarządzania/modyfikowania i niespecjalnie sformalizowane. Coś bardziej na własny użytek, aby trochę złapać ramy projektu, zapisać jakieś założenia aby nie uciekły.

Dla przykładu obecnie klient zlecił mi taki mały projekcik do zarządzania bazą produktową - wiele sklepów, wiele źródeł danych, kilka języków - trzeba to jakoś pożenić aby przy aktualizacji danych np. u producenta dane zmieniały się w wybranych sklepach itd. Z jednej strony nie jest to jakiś ogromny projekt, z drugiej jednak za 150h na to pójdzie i pewnie w przyszłości będzie trzeba to rozwijać. Architektura oparta o kolejki, jakieś sekwencje zdarzeń itp. Fajnie byłoby to sobie jakoś spisać.

Jak do takich tematów podchodzicie, czego używacie? Jakaś mindmapa do łapania luźnych pomysłów + readme + wiki w projekcie? A może jakiś bardziej system notatek?

ja teraz używam głównie plików tekstowych. W formacie markdown piszę, ale i tak raczej rzadko patrzę nad podgląd (jednak samo pisanie w formacie markdown sprawia, że mam podświetlanie składni, mogę wrzucać snippety kodu i składnia się tam podświetli itp.).
No i w tych plikach spisuję strumień świadomości, co mi przyjdzie do głowy. Nawet jakieś takie luźne pomysły. Albo jak planuję jakieś API to piszę przykłady kodu (które nie muszą być nawet zgodne z finalną wersją tego, co faktycznie zrobię, ale raczej takie przykłady "jak chcę, żeby to wyglądało").

Poza tym jak trzeba to i narysuję coś na kartce papieru, ale zwykle na luźnych kartkach piszę, a potem się to wala(chociaż np. niedawno chciałem dopisać testy do czegoś, co nie miało testów i nie byłem pewien "jak ja to wtedy zrobiłem?", ale udało mi się znaleźć kartkę papieru, na której był schemat tego, co akurat testowałem, więc to mi dużo ułatwiło.

Ja zaczynam od spisania co ja wgl chcę zrobić (wymagania). Potem robię ERD (bo łatwiej mi ogarnąć domenowo o co chodzi z modelu danych niż z opisu). Jeżeli mały projekt to tworzę wszystkie taski i wpycham do backlogu. Potem w między czasie jakieś drobne Wiki na Gitlabie i w zasadzie tyle. Przy większych projektach to już rozpisuje schemat komunikacji między serwisami, integracje itd. Raczej używam draw.io (bieda).

W najnowszej aplikacji użyłem od planowania FreePlane - to taka aplikacja do mindmapowania. Musze przyznać, że dość fajnie się sprawdza na etapie koncepcyjnym. Można robić notatki od ogółu do szczegółu, dodawać ukryte notatki w poszczególnych nodach. Jak chcesz zmienić układ notatek to zawsze można łatwo przenosić/reorganizować (tego brakowało mi na kartce). Reasumując fajnie się sprawdza. Nie jest to rozwiązanie wszystkich problemów - np. diagram interakcji między eventami z poszczególnych kolejek musiałem już sobie rozrysować w draw.io (dla odmiany średnio poręczne, chyba na dłużej przy tym nie zostanę).
Nie jest to lek na wszystko, ale zadziwiająco dobrze sprawdza się taka rozwijana mind mapa bo am w jednym miejscu podstawowy diagram bazy (zawsze robiłem w formie tekstowe), pytania do odpowiedzi na później, luźne notatki z pomysłami itp.

Ostatnio w modzie/na hajpie są ADR, czyli krótkie notatki które powstają w trakcie podejmowania ważnych decyzji które są trudne do zmiany z perspektywy czasu (co niektórzy uważają za definicję architektury). Wersjonowane są w gicie zaraz obok kodu źródłowego i pisane w markdownie.
Technology Radar : Architecture Decision Records
joelparkerhenderson / architecture_decision_record
przykładowe ADR z przykładowego projektu