O dokumentacji projektów słów kilka

Witam!

Ten post powstał z dwóch powodów:

1. Po przeczytaniu artykułu na devBlogi.pl postanowiłem w miarę jak najwięcej pisać, by to co piszę, stawało się coraz lepsze i coraz ciekawsze. Jak się okaże później, nie tylko autor wspomnianego artykułu tak myśli :)
2. Udało mi się otrzymać zgodę na ciekawy projekt na uczelni (aplikacja na potrzeby zaliczenia przedmiotu Inżynieria Oprogramowania, z bardzo dużą szansą na wdrożenie na uczelni). Z kolegą, z którym jestem w zespole postanowiliśmy podejść do tego profesjonalnie i zacząć całe przedsięwzięcie od stworzenia dobrego projektu i dokumentacji (mogliśmy tworzyć projekt za pomocą metody kaskadowej lub zwinnej, zdecydowaliśmy się na tę drugą). Gdy nasz wykładowca się o tym dowiedział podsunął nam bardzo ciekawy artykuł. Ale o tym zaraz.

Kiedy na wcześniejszych latach studiów tworzyłem z kolegami oprogramowanie na zaliczenie często gęsto nasza dokumentacja mieściła się na 2 stronach A4 stworzonych tylko po to, żeby wykładowca miał ogólny pogląd na projekt i mógł, mając harmonogram prac, rozliczać nas z postępów w pracy. Na samym początku nie jest to problemem. Każdy zbudował swoją część komponentów, udostępnił prototypy i ... nagle nic do siebie nie pasowało. Spędziliśmy z goła 1,5 doby na przerabianiu bibliotek tylko po to, żeby ze sobą współpracowały. Efekt był opłakany, a fakt, że aplikacja w ogóle się skompilowała i uruchomiła przypisuje gorliwym modlitwom na 5 minut przed oddaniem. Za drugim razem było z goła inaczej. Tak zabraliśmy się za dokumentacje, ale było jej tak dużo, że wiele wymagań się pokrywało, jeszcze więcej było ze sobą zwyczajnie sprzecznych i suma summarum nic z tego nie wyszło...

Całe szczęście Joel Spolsky dla takich jak ja stworzył serie artykułów mówiących o tym czym jest, a czym nie jest specyfikacja projektu, kto i dlaczego powinien ją sporządzać oraz jak (w dużym skrócie) powinno się to robić. Cała seria (Painless Functional Specifications) składa się z czterech części:

1. "Part 1 - Why Bother?" mówiąca o sensie tworzenia specyfikacji i pokazująca najczęstsze przyczyny nie robienia tego
2. "Part 2 - What's a Spec?" pokazująca jak może (i powinna) wyglądać przykładowa specyfikacja, wyjaśniając również do kogo i w jaki sposób powinna być ona adresowana
3. "Part 3 - But... How?" mówi o tym kto powinien, a kto zdecydowanie nie powinien zajmować się w firmie tworzeniem specyfikacją projektu
4. "Part 4 - Tips" wyjaśnia 5 podstawowych zasad tworzenia specyfikacji

Osobiście najchętniej czytałem część drugą. Byłem bardzo zaskoczony faktem, jak daleko odchodziłem od właściwej (a może raczej jednej z wielu właściwych) ścieżek tworzenia dokumentacji. Wielu rzeczy (jak scenariusze) zwyczajnie nie umieszczałem, bo nie miałem pojęcia, że mogą się one komukolwiek przydać. Natomiast z ostatnią zasadą (artykuł "Part 4 - Tips") nie mogę się zgodzić. Rozumiem, że formatka dokumentacji musi być elastyczna, dostosowana do elementu, który ma opisywać, ale pewien standard powinien zostać zachowany. To tak jak z dokumentacją w formie JavaDoc - człowiek poznaje ogólny schemat, przyzwyczaja się do niego i w późniejszym czasie jest mu o wiele łatwiej pracować z tego typu dokumentacją. Ale brak standardu może wprowadzić jeszcze większe zamieszanie, którego przecież staramy się uniknąć :)

A jak to jest u Was? Czy raz napisana dokumentacja ląduje na półce i nikt jej nie czyta? A może jest jej zwyczajnie za dużo i ciężko jest odnaleźć interesujące Was informacje? Chętnie dowiedziałbym się jak to jest gdzie indziej niż na uczelni wyższej :)

Pozdrawiam i do następnego razu!