Aleksander Olszewski

Aleksander Olszewski Kierownik Projektów
IT, PRINCE2
Practitioner

Temat: A ja się dziwię programistom, przepraszam Was...

Paweł Włodarski:
...
"jakie macie wytyczne programowania" - uczynić świat lepszym
"jak dokładnie prowadzicie projekty" - Scrum zmieniony pod nasze potrzeby
"co teraz robicie" - takie fajne narzędzie do geolokalizacji
"co wydacie za 4 miesiące" - no właśnie to fajne narzędzie"

Pawle, cieszę się, że możesz otwarcie powiedzieć nad czym pracujesz i co oddasz za kilka miesięcy. Natomiast mnie obowiązuje tajemnica firmowa i nie wszystko co wiem mogę powiedzieć. Dlatego unikałem i będę unikał dyskusji, które mogą doprowadzić do ujawnienia tajemnicy firmowej w mojej obecnej firmie i firmach poprzednich.

To co nie może stanowić tajemnicy, to diagramy, wyidealizowane koncepcje oraz idealne rozwiązania. I w tych terminach mogę się poruszać.
Aleksander Olszewski

Aleksander Olszewski Kierownik Projektów
IT, PRINCE2
Practitioner

Temat: A ja się dziwię programistom, przepraszam Was...

Paweł Włodarski:
...
Ehh, niepotrzebnie czujesz się atakowany. Chciałem tylko zrozumieć twój tok myślenia z tym kodem bo o ile dyskusyjne koncepcje dokumentacji dokumentacji pojawiają się od czasu do czasu na forach o tyle tego przejścia od kodu do problemu jeszcze nie spotkałem. Nie chcesz dyskutować, ok, nic na siłę.

Jeśli chodzi o kod, to oczywiście jest:

1. Czytelny kod: tu się kłania notacja węgierska, notacja camelCase, oraz notacja pascalowa. Są też wcześniejsze notacje, np. na zasadzie kodów (próba obejścia ograniczeń języka --- np. zmienna do 8 znaków) lub z podkreślnikiem (ale ta forma przyjęła się głownie w bazach danych). Do tego dochodzi kilka paradygmatów (np. DDD), stylu kodowania (np. wcięcie 4 spacji) i dobrych praktyk (np. eliminacja wszystkich negatywnych scenariuszy już na początku metody).

2. Samodokumentujący się kod. Tu chodzi o zestaw znaczników, dostarczany przez zewnętrze/wbudowane narzędzie, służące do generowania dokumentacji (głównie API) na podstawie komentarzy w kodzie. Mam tu na myśli Javadoc, RDoc, PHPDoc, Doxygen (osobiście do mnie to narzędzie nie trafia).

3. Samoopisujący się kod. Nie wiem czy znajdziesz to w Google. Raczej teraz coraz częściej będą wyskakiwać wyniki naszej dyskusji na GL :) Wedle mnie jest to zwyczajnie wymówka przed wejściem w etap analizy i projektowania. Argumentacja jest taka: mamy przecież czytelny kod (standardy kodowania), mamy przecież samodokumentujący się kod (generator dokumentacji) po co nam analiza i projektowanie? Programista usiądzie i napisze.

Argument samoopisującego się kodu jest zasadny tylko i wyłącznie w jednej sytuacji: ten sam programista od początku do końca, od etapu projektowania do etapu przekazania zajmuje się tym samym komponentem. Ten sam programista również zajmuje się rozwojem komponentu i jego utrzymaniem. Jak ten programista pójdzie na urlop, rozwój komponentu też idzie na urlop.

Owszem możemy temu zaradzić wprowadzając programowanie w parach. Wtedy mamy dwóch programistów, ale tę parę trzeba utrzymać tak długo, aż komponent zostanie ukończony, wszystkie poprawki muszą być obgadywane z udziałem tej pary, a same poprawki najlepiej przeprowadzać z jednym z tych programistów w parze z innym. Wtedy zapewnimy propagację wiedzy w zespole.

Nie wszystkim firmom to pasuje. Powyższy akapit idealnie wpisuje się w potrzeby małego zespołu programistów (np. 2-3 pary), który wykonuje system na potrzeby wewnętrzne.

Można oczywiście przeorganizować duży projekt i duży zespół pod tą koncepcję, ale duże firmy (zarówno jak strona zamawiająca tak i wykonawca) z reguły nie akceptują taki poziom ryzyka i chcą bardziej sformalizowaną metodykę prowadzenia projektu oraz bardziej formalną dokumentacje (np. projekt funkcjonalny, architekturę systemu, podręcznik użytkownika oraz ewentualnie za dodatkową opłatą API).

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

.Ten post został edytowany przez Autora dnia 09.08.16 o godzinie 21:45
Aleksander Olszewski

Aleksander Olszewski Kierownik Projektów
IT, PRINCE2
Practitioner

Temat: A ja się dziwię programistom, przepraszam Was...

Paweł Włodarski:

Teraz załóżmy sobie, że mamy coś takiego jak środowisko programistyczne (nie mylić z IDE) czyli zespół zmiennych ludzki i pozaludzkich, który da się scharakteryzować wieloma zmiennymi.

I tak na przykład : (w dużym uproszczeniu):
Przepis na klęskę numer 1: Weź zespół studentów i zrób z nich "samoorganizujacy się TEAM"

Z tym się akurat zgadzam. zespół, który nie ma wystarczającego doświadczenia, nie ma wspólnego języka i odpowiedniej wiedzy nie może sam się zorganizować. Dodam też, że doświadczony zespół ma z tym problemy. Działa tu prawo Parkinsona, prawa Murphy'ego, entropia informacji, cicha wiedza i pewnie mógłbym wymienić kilka innych zjawisk :)
Przepis na klęskę numer 2: Weź zespół ekspertów i każ trzymać się ściśle zaprojektowanej z góry architektury.

A tu kompletnie nie zgadzam się. Znane są ambitne projekty, np. C3, które zostały zarzucone właśnie z powodu braku dokumentacji. Problem nie jest taki prosty, jak czasami go, Pawle, podajesz. Niektóre projekty padają również z powodu braku zaprojektowanej architektury. Jeśli odnosisz się w tym miejscu do Scrum, to zauważ, że ma on ograniczenia co do liczby uczestników projektu, a niektóre projekty muszą mieć sporą liczbę programistów, np. 50.
A do tych przemyśleń skłoniło mnie to, że w kontekście mojej wiedzy, mojej percepcji i mojego doświadczenia ta uwaga o programowaniu w parach nie ma sensu. U mnie zmieniamy się parami dosyć często przez co wiedza odnośnie kodu jest rozprzestrzeniona (nie mylić z podzielona) i mamy większy truck number (truck number - ilość osób, która musi wpaść pod samochód aby projekt legł w gruzach, w przykładzie z programistą, który idzie na urlop truck number=1). Ogólnie słowo klucz to współwłasność kodu.

Niestety nie zawsze można osiągnąć odpowiedni współczynnik współdzielenia kodu, np. krótki projekt z dużą liczbą programistów, kilka zespołów projektowych, rozproszony model pracy/współpracy, bardzo długi projekt (znów odniosę się do projektu C3). Ale w niektórych sytuacjach, to co piszesz świetnie się sprawdza.
Mogę teraz się domyślać, że u ciebie idea : para osób ściśle związana z danym kawałkiem kodu ma sens w szerszym kontekście, który tutaj w dyskusji wytłumaczyć będzie trudno. Być może konkretne osoby są rozliczane za konkretne fragmenty aplikacji.

Tu dam jako przykład sytuację, gdy straty czasu na rotację par nie są akceptowane. Przyznasz, że stała para napisze komponent szybciej niż para, która codziennie się zmienia.
Podobnie może być z tą kwestią z podejściem do poprawności testów. Teraz mogę przypuszczać, że gdy tworzysz wstępnie projekt implementacji idzie za tym potrzeba specjalnej analizy testów jednostkowych. Dla odmiany gdy poprawnie używasz TDD tworzysz niejako aplikację szytą na testy. Masz poprawne testy zaś niekoniecznie poprawna aplikację stąd kolejne linie obrony w postaci testów integracyjnych i funkcjonalnych. Zwróć proszę uwagę na istnienie w poprzednim zdanie słowa "poprawne" bo TDD nie jest srebrną kulą. Może pojawić się pytanie po co dalej te testy mutacyjne. Bo generalnie człowiek, czego by nie stosował, prędzej czy później się pomyli.

Tu temat jest dosyć obszerny. Na ogół nie mylę TDD z innym testowaniem. Testy jednostkowe powstają przed spisaniem metody. Natomiast same testy jednostkowe nie wystarczają do kompletnego przetestowania, a testy mutacyjne nie załatwiają wiele więcej. Zgodnie z V-modelem testy jednostkowe są pierwszym krokiem w testowaniu SI. Testy integracyjne i funkcjonalne mają inną funkcję i przeznaczenie. Są tak samo potrzebne jak i testy jednostkowe.

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

.Ten post został edytowany przez Autora dnia 09.08.16 o godzinie 21:45
Aleksander Olszewski

Aleksander Olszewski Kierownik Projektów
IT, PRINCE2
Practitioner

Temat: A ja się dziwię programistom, przepraszam Was...

Paweł Włodarski:
...
W podanym przykładzie absolutnie nie chodziło mi brak dokumentacji. Dokumentacja może powstać na wiele sposobów i mieć różne formy. Dokumentacja jest zajebista ale tylko ta niezbędna i aktualna. Ba! Jeśli założymy, że ta nieaktualna dokumentacja się nie liczy to można by się nawet spierać czy projekty prowadzone "edzajlem" nie są najlepiej udokumentowanymi projektami na tej planecie ;)

Ciekaw jestem co o Tym myślisz :) http://www.goldenline.pl/forum/2509562/spadek

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

.Ten post został edytowany przez Autora dnia 09.08.16 o godzinie 21:47
Piotr Głudkowski

Piotr Głudkowski Rzucam się na
wszystko to, co jest
ciekawe i wymaga
rusze...

Temat: A ja się dziwię programistom, przepraszam Was...

/.../
Odnośnie tematu na twojej grupie to również ten sam Jakub zadał tam właściwe pytanie " po co jest dokumentacja".

Można nawet pobawić się w ćwiczenia mentalne na poziomie abstrakcji wyżej: Czy można traktować ilość dokumentacji jako miarę problemów komunikacyjnych w zespole (tudzież miarę poziomu braku zaufania)?

Pozwolę sobie wtrącić swoje trzy grosze.
Poruszyłeś dwie ważne kwestie.
1. Po co jest dokumentacja?
To jest właściwie kluczowa kwestia. Jeśli dokumentacja ma być traktowana jako jedyna droga przepływu informacji pomiędzy komórkami zespołu (analitycy->projektanci->programiści->serwis), to sprawdzi się to tylko w wielkich projektach, prowadzonych w dużych firmach przez długi okres - tylko wtedy przeczytanie fragmentu dokumentacji może okazać szybsze (bardziej wydajne) od bezpośredniej dyskusji z odpowiednią osobą (analitykiem? projektantem?). W przypadku naprawdę wielkich projektów ilość informacji często przekracza możliwości percepcyjne człowieka, dodatkowo pojawić się może tutaj aspekt rotacji zatrudnienia wymuszający ciągłe przekazywanie wiedzy kolejnym osobom, co prowadzi do powstawania raczej legend ludowych ("mój poprzednik przekazał mi, że jego poprzednik usłyszał od swojego ppoprzednika, że to ma działać tak"). W takiej sytuacji dokumentacja jest niezbędna. A czas jej tworzenia? Cóż, wliczy się w projekt - skoro trwać on ma np. rok, to 3 tygodnie na kwity znikną jak kropla w morzu. Pracowałem w firmie, w której dział serwisu (oczywiście mowa o serwisie oprogramowania) był na tyle oddalony (zarówno organizacyjnie, jak i geometrycznie) od działów produkcyjnych, że wymiana informacji mogła zachodzić jedynie drogami formalnymi - a w takim przypadku dokumentacja zawsze będzie szybsza niż proszenie swojego szefa, żeby skontaktował się z szefem programistów, żeby on wyznaczył programistę, który wyjaśni mi jak coś działa albo dlaczego coś działa w taki a nie inny sposób.
Oczywiście opisane powyżej sytuacje są ewidentnie chore - ale, niestety, są często spotykane (sam pracowałem w takiej firmie, sorry: "korporacji").

2. Ilość i jakość dokumentacji.
W zasadzie to nie ilość dokumentacji, ale jej jakość warunkuje jej użyteczność. Widziałem swego czasu piękną dokumentację do systemu, napisaną przez kogoś z firmy o trzyliterowej nazwie, w której były pięknie, strukturalnie i systematycznie opisane wszystkie przypadki użycia. Dokumentacja miała tylko jedną wadę: była całkowicie nieużyteczna - znalezienie w niej czegokolwiek wymagało przeszukiwania olbrzymich ilości pięknych, kolorowych tabelek i biegania na zmianę do przodu i do tyłu. Kicha do kwadratu. Dodam tylko, że było tego ponad 300 stron. Piękna, bardzo potrzebna, ale niestety całkowicie nieużyteczna robota.
Widziałem również podobną dokumentację napisaną przez inną firmę do innego systemu - ta miała ponad 500 stron, ale znalezienie w niej dowolnego szczegółu trwało może minutę, czasem dwie. Też przypadki użycia, też zestrukturyzowane, ale widać, że ktoś, kto ją tworzył, myślał o jej czytelniku. Ja wiem, że programiści nie potrafią często pisać ładnie, składnie itd - ale nie w tym rzecz: pisząc kwity trzeba po prostu pamiętać, do czego one mają służyć, i trzeba formułować zawartą w nich wiedzę w taki sposób, żeby nie tylko była obecna, ale i była dostępna i użyteczna.
Kiedyś popełniłem jakiś middleware, który potem chodził w kilkudziesięciu miejscach w kraju w trybie 24/7/365 i objęty był ostrą umową serwisową. Napisałem do tego chyba ponad 400 stron dokumentacji - zmieniałem ją dotąd, aż serwis stwierdził, że łatwiej im znaleźć coś w tej dokumentacji, niż znaleźć mnie (nie chowałem się specjalnie bynajmniej). I to był cel jej utworzenia. Trwało to raptem ze 2 miesiące.
Później tworzyłem inne kwity - ale już wiedziałem jak, i dzięki temu zwykle były przydatne. Oczywiście w przypadku dokumentacji będącej analizą albo projektem, targetem nie będzie serwis, ale np. programiści - ale to jest jedyna różnica.
Po prostu: dokumentacja tworzona bezmyślnie, na wagę, nadaje się z definicji do spalenia. Dokumentacja sensowna przyda się zawsze.

I jeszcze jedno: mi średni wychodzi tak, że dziennie mogę zrobić 7...9 stron dobrej, merytorycznej dokumentacji wraz z jej sformatowaniem - na tip top.
Oczywiście formatowanie robię na końcu, jak już wszystko jest napisane - i dla tego jest to wartość średnia.
Moi znajomi, którzy też już pisali jakieś większe kwity, twierdzą podobnie.
Wynika z tego jedno: jeśli ktoś w 7 dni zrobił 50 stron kwitów, to mają one szansę być sensowne. Ale jeśli ktoś robi to w 2 lub 3 dni, to można z góry założyć, że jest to gówno i strata czasu.
Jeśli kogoś skrzywdziłem - sorry.
Takie jest moje subiektywne zdanie, oparte na doświadczeniach.

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

Pozwolę sobie wtrącić swoje trzy grosze.
Poruszyłeś dwie ważne kwestie.

1. Po co jest dokumentacja?
To jest właściwie kluczowa kwestia. Jeśli dokumentacja ma być traktowana jako jedyna droga przepływu informacji pomiędzy komórkami zespołu (analitycy->projektanci->programiści->serwis), to sprawdzi > się to tylko w wielkich projektach

Czy to znaczy, że w małych i średnich projektach dokumentacja jest zbędna ?
, prowadzonych w dużych firmach przez długi okres

A w średnich firmach przez długi okres czasu (dobre projekty IT kończą swój żywot wraz z klientem) ?
- tylko wtedy przeczytanie fragmentu dokumentacji może okazać szybsze (bardziej wydajne) od bezpośredniej dyskusji z odpowiednią osobą (analitykiem? projektantem?).

Czyli dokumentacja powstaje po to, żeby szybciej przekazywać 'informację mówioną' ?

Czy można stworzyć dobrą dokumentację projektu IT bez użycia formalnych języków / notacji ?
2. Ilość i jakość dokumentacji.
W zasadzie to nie ilość dokumentacji, ale jej jakość warunkuje jej użyteczność.

Czy można jakoś zmierzyć jakość (użyteczność) dokumentacji ?

Kurcze dużo pytań ostatnio zadaje .. ;p
Piotr Głudkowski

Piotr Głudkowski Rzucam się na
wszystko to, co jest
ciekawe i wymaga
rusze...

Temat: A ja się dziwię programistom, przepraszam Was...

Jeśli dokumentacja ma być traktowana jako jedyna droga przepływu informacji pomiędzy komórkami zespołu (analitycy->projektanci->programiści->serwis), to sprawdzi > się to tylko w wielkich projektach

Czy to znaczy, że w małych i średnich projektach dokumentacja jest zbędna ?
Nie. To znaczy dokładnie to, co napisałem: w wielkich jest niezbędna, bo staje się jedyną drogą przekazywania wiedzy.
W małych inne drogi są równie efektywne, dlatego brak dokumentacji (albo jej szczątkowa postać) zwykle nie powoduje katastrofy - co nie znaczy, że jest zbędna.
A w średnich firmach przez długi okres czasu (dobre projekty IT kończą swój żywot wraz z klientem) ?
- tylko wtedy przeczytanie fragmentu dokumentacji może okazać szybsze (bardziej wydajne) od bezpośredniej dyskusji z odpowiednią osobą (analitykiem? projektantem?).

Czyli dokumentacja powstaje po to, żeby szybciej przekazywać 'informację mówioną' ?
Nie. Dokumentacja jest głównym repozytorium wiedzy o projekcie na wszystkich jego płąszczyznach technologicznych i we wszystkich obszarach funkcjonalnych.
Dlatego jestem ogromnym zwolennikiem robienia DOBREJ dokumentacji ZAWSZE.
Natomaist powyżej pisałem o przypadkach, kiedy bez niej jest katastrofa.
Czy można stworzyć dobrą dokumentację projektu IT bez użycia formalnych języków / notacji ?
Oczywiście, że tak.
Forma dokumentacji zależy wprost od jej targetu - dokumentacja ma być zrozumiała dla czytającego - inaczej jest plikiem papieru na makulaturę.
2. Ilość i jakość dokumentacji.
W zasadzie to nie ilość dokumentacji, ale jej jakość warunkuje jej użyteczność.
Czy można jakoś zmierzyć jakość (użyteczność) dokumentacji ?
Czy można zmierzyć pogodę? Czy można zmierzyć sympatię?
Mam wrażenie, że w dzisiejszych czasach, zdominowanych przez rozmaite wyścigi szczurów i zabiegi konkurencyjne, zatraciły się główne prawdy IT:
- binarka jest dla maszyny
- kod programu jest dla ludzi
- dokumentacja jest dla ludzi
- itd.

A to, co jest dla ludzi, mierzy się reakcją ludzi na to coś. Więc miara jakości dokumentacji jest prosta: jeśli ktoś chce ją czytać i z niej korzystać - jest dobra. Jeśli leży na pólce i się kurzy - jest do dupy.
I, proszę, nie pytaj mnie dalej, jaki jest przepis na dobrą dokumentację, bo go nie ma.
Wiem, że w dzisiejszych czasach wielu "fachowców" oczekuje, że dokumentację wygenerują automaty - tyko czy aby na pewno to jest dokumentacja dla ludzi?
W życiu nie widziałem dobrej dokumentacji, wygenerowanej automatycznie. Owszem, może ona służyć jako wykaz obiektów, funkcji, tabel, pól, relacji i tego wszystkiego, czego nie chce nam się wypisywać ręcznie. Ale do dobrej dokumentacji ma się to tak, jak słownik do książki.

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

- tylko wtedy przeczytanie fragmentu dokumentacji może okazać szybsze (bardziej wydajne) od bezpośredniej dyskusji z odpowiednią osobą (analitykiem? projektantem?).

Czyli dokumentacja powstaje po to, żeby szybciej przekazywać 'informację mówioną' ?
Nie. Dokumentacja jest głównym repozytorium wiedzy o projekcie na wszystkich jego płąszczyznach technologicznych i we wszystkich obszarach funkcjonalnych.

Proszę o jakiś precyzyjniejszy opis (duży współczynnik signal/noise ;)

A może inaczej; załóżmy konkretną sytuację: PM ma dokumentację (i tylko ją, implementacja jeszcze nie wystartowała) z dokładnie opisaną domeną (analityk) i architekturą. Do czego taka dokumentacja może posłużyć PM'owi ?

Inna sytuacja: do czego taka dokumentacja może przydać się 'innej firmie' przy implementacji nowej funkcjonalności X (zakładam, że wiersza wersja systemu została wdrożona i działa).
Czy można stworzyć dobrą dokumentację projektu IT bez użycia formalnych języków / notacji ?
Oczywiście, że tak.
Forma dokumentacji zależy wprost od jej targetu - dokumentacja ma być zrozumiała dla czytającego - inaczej jest plikiem papieru na makulaturę.

Ostatecznym targetem jest procesor...

Największy problem jest właśnie z tym, że realizacja projektu IT to trochę taka zabawa w głuchy telefon z tym, że wszyscy się słyszą, ale nikt się - potencjalnie - nie rozumie (a przynajmniej nie jest tego świadomy). Stosowanie języków formalnych ma temu zapobiec. Przynajmniej tak mi się wydaje.

Podobnie jest z resztą w przypadku tej dyskusji - ktoś może stwierdzić, że uprawiam pyskówkę i trolizm a tak na prawdę zadaję te wszystkie 'wredne' pytania bo chcę zrozumieć Pańskie poglądy.
2. Ilość i jakość dokumentacji.
W zasadzie to nie ilość dokumentacji, ale jej jakość warunkuje jej użyteczność.
Czy można jakoś zmierzyć jakość (użyteczność) dokumentacji ?
Czy można zmierzyć pogodę? Czy można zmierzyć sympatię?

Czy to mam odpowiedzieć przełożonemu, kiedy mnie zapyta, czy na podstawie danej dokumentacji, 'mój' zespół jest w stanie stworzyć system ?
Mam wrażenie, że w dzisiejszych czasach, zdominowanych przez
rozmaite wyścigi szczurów i zabiegi konkurencyjne, zatraciły się główne prawdy IT:
- binarka jest dla maszyny
- kod programu jest dla ludzi
- dokumentacja jest dla ludzi
- itd.

Nie do końca. Od tych ludzi wymaga się pewnych kompetencji
A to, co jest dla ludzi, mierzy się reakcją ludzi na to coś. Więc miara jakości dokumentacji jest prosta: jeśli ktoś chce ją czytać i z niej korzystać - jest dobra. Jeśli leży na pólce i się kurzy - jest do dupy.

Raz o ty pisałem i nie chcę się powtarzać.
I, proszę, nie pytaj mnie dalej, jaki jest przepis na dobrą dokumentację, bo go nie ma.

Racja, jako takie 'przepisy na dobrą dokumentację' nie istnieją. Nie można ich 'wykopać' i nie podyktuje ich 'siła wyższa'. Podobnie jak z młotkiem - nikt go nie wykopał i nie było dołączonej do niego instrukcji obsługi.

Po prostu trzeba takią stworzyć - sumując swoją wiedzę o klientach, programistach i technologii.
Dokumentacja to po prostu 'plan projektu' jak ktoś się na tym zna to wie jak to zrobić potrafi zaplanować implementację i rozwój systemu.

Jeśli ktoś mówi, że dokumentacja ma być o wszytkim i precyzyjna to ... ma rację, ale niech jeszcze wytłumaczy co to znaczy 'wszystko' i 'dokładnie' bo nie każdy (np. ja) 'wie wszystko i dokładnie'.
Wiem, że w dzisiejszych czasach wielu "fachowców" oczekuje, że dokumentację wygenerują automaty - tyko czy aby na pewno to jest dokumentacja dla ludzi?

Nie; ale nie musi skoro radzą sobie z nią automaty.
W życiu nie widziałem dobrej dokumentacji, wygenerowanej automatycznie. Owszem, może ona służyć jako wykaz obiektów, funkcji, tabel, pól, relacji i tego wszystkiego, czego nie chce nam się wypisywać ręcznie. Ale do dobrej dokumentacji ma się to tak, jak słownik do książki.

To pewnie dlatego w C# istnieje klasa Dictionary a nie ma klasy Book...
Po prostu zmowa maszyn ;)
Piotr Głudkowski

Piotr Głudkowski Rzucam się na
wszystko to, co jest
ciekawe i wymaga
rusze...

Temat: A ja się dziwię programistom, przepraszam Was...

Jakub Wojt:
Nie. Dokumentacja jest głównym repozytorium wiedzy o projekcie na wszystkich jego płąszczyznach technologicznych i we wszystkich obszarach funkcjonalnych.

Proszę o jakiś precyzyjniejszy opis (duży współczynnik signal/noise ;)
Tu chodzi o możliwość odtworzenia warunków początkowych: wyobraźmy sobie, że jesteś kimś tam w projekcie, masz określone kompetencje, otrzymałeś dokumentację z wcześniejszych faz projektu i jesteś w stanie znaleźć w niej wszystko, co dotyczy Twojej pracy w tym projekcie.
I teraz, nagle na Twoim miejscu pojawia się ktoś inny, o zbliżonych kompetencjach. Chodzi o to, żeby z tych samych kwitów mógł się dowiedzieć wszystkiego, co wiedziałeś Ty (oczywiście mowa o wiedzy niezbędnej do pracy na danym etapie projektu).
Jeśli czegoś nie ma w kwitach -> dokumentacja jest niepełna i wymaga uzupełnienia.

A może inaczej; załóżmy konkretną sytuację: PM ma dokumentację (i tylko ją, implementacja jeszcze nie wystartowała) z dokładnie opisaną domeną (analityk) i architekturą. Do czego taka dokumentacja może posłużyć PM'owi ?
Cholera wie :) A poważniej - zależy od organizacji przyjętej podczas prowadzenia projektu. W wielu projektach, w których uczestniczyłem, to właśnie PM pełnił rolę nadzorcy repozytorium dokumentacji - być może większości nie rozumiał, ale to on wiedział, gdzie dany kwit jest.
Inna sytuacja: do czego taka dokumentacja może przydać się 'innej firmie' przy implementacji nowej funkcjonalności X (zakładam, że wiersza wersja systemu została wdrożona i działa).
Do niczego :) Przecież nie powinniśmy być samobójcami: jeśli klient chce, żeby ktoś inny (tańszy?) mu rozbudowywał projekt, zabierając nasze (potencjalnie) $$$, to chyba nie będziemy mu w tym pomagać zbytnio?
A poważniej: jeśli rzeczywiście jest taka konieczność, formalne notacje będą niezbędne.
Czy można stworzyć dobrą dokumentację projektu IT bez użycia formalnych języków / notacji ?
Oczywiście, że tak.
Forma dokumentacji zależy wprost od jej targetu - dokumentacja ma być zrozumiała dla czytającego - inaczej jest plikiem papieru na makulaturę.

Ostatecznym targetem jest procesor...
:)
Ja to dzielę inaczej:
1. Dokumentacja wewnętrzna: przeznaczona do przekazywania wiedzy między komórkami firmy, ew. np. między nami a naszymi podwykonawcami: tutaj głównym wymogiem będzie utrzymanie się w konwencji, wypracowanej w organizacji. A to, na ile ona jest zgodna ze standardami "zewnętrznymi", ma znaczenie wtórne.
2. Dokumentacja zewnętrzna: za nią de facto płaci klient. W zasadzie powinien ją dostać w takiej postaci, w jakiej oczekuje. Jeśli wystarczy mu graf przejść między formatkami + słowny opis formatek, to powinien to dostać. Jeśli chce manuala dla end-usera, napisanego łopatologicznie, powinien to dostać. Uszczęśliwianie klienta "na siłę" UML-ami itd jest stratą papieru i naszego czasu, no i na takie okazywanie przez nas naszego profesjonalizmu malo który klient się nabierze.
Największy problem jest właśnie z tym, że realizacja projektu IT to trochę taka zabawa w głuchy telefon z tym, że wszyscy się słyszą, ale nikt się - potencjalnie - nie rozumie (a przynajmniej nie jest tego świadomy). Stosowanie języków formalnych ma temu zapobiec. Przynajmniej tak mi się wydaje.
To jest teoria :) Coś w stylu regulaminu w wojsku. Ale tak jak regulamin nie zastąpi myślenia i zdrowego rozsądku, tak i formalne notacje nie zwalniają nas z konieczności dobrego przemyślenia, dla kogo kwity robimy i jaka powinna być ich postać.
Podobnie jest z resztą w przypadku tej dyskusji - ktoś może stwierdzić, że uprawiam pyskówkę i trolizm a tak na prawdę zadaję te wszystkie 'wredne' pytania bo chcę zrozumieć Pańskie poglądy.
Na imię mam Piotrek :)
2. Ilość i jakość dokumentacji.
W zasadzie to nie ilość dokumentacji, ale jej jakość warunkuje jej użyteczność.
Czy można jakoś zmierzyć jakość (użyteczność) dokumentacji ?
Czy można zmierzyć pogodę? Czy można zmierzyć sympatię?

Czy to mam odpowiedzieć przełożonemu, kiedy mnie zapyta, czy na podstawie danej dokumentacji, 'mój' zespół jest w stanie stworzyć system ?
Możesz :) A poważniej: jeśli liderzy zespołu, po zapoznaniu się z tym, co napisałeś stwierdzą, że im to wystarczy, to masz już odpowiedź.
Mam wrażenie, że w dzisiejszych czasach, zdominowanych przez
rozmaite wyścigi szczurów i zabiegi konkurencyjne, zatraciły się główne prawdy IT:
- binarka jest dla maszyny
- kod programu jest dla ludzi
- dokumentacja jest dla ludzi
- itd.

Nie do końca. Od tych ludzi wymaga się pewnych kompetencji
Tutaj się w 100% zgadzam.
Ale ludzie są ludźmi, i zawsze lepiej im się czyta coś, co przygotowane zostało dla nich.
Jeśli ktoś mówi, że dokumentacja ma być o wszytkim i precyzyjna to ... ma rację, ale niech jeszcze wytłumaczy co to znaczy 'wszystko' i 'dokładnie' bo nie każdy (np. ja) 'wie wszystko i dokładnie'.
Jezuu... a wydawało mi się, że informatycy tym się różnią od prawników, że mają "równo" pod kopułą i nie czepiają się słówek :))))
Są 3 czynniki, które ułatwiają odpowiedź na tak zadane pytanie:
1. Zdrowy rozsądek
2. Zdrowy rozsądek
3. Zdrowy rozsądek
Wiem, że w dzisiejszych czasach wielu "fachowców" oczekuje, że dokumentację wygenerują automaty - tyko czy aby na pewno to jest dokumentacja dla ludzi?

Nie; ale nie musi skoro radzą sobie z nią automaty.
To niech sobie automaty ją też robią.
W życiu nie widziałem dobrej dokumentacji, wygenerowanej automatycznie. Owszem, może ona służyć jako wykaz obiektów, funkcji, tabel, pól, relacji i tego wszystkiego, czego nie chce nam się wypisywać ręcznie. Ale do dobrej dokumentacji ma się to tak, jak słownik do książki.

To pewnie dlatego w C# istnieje klasa Dictionary a nie ma klasy Book...
Po prostu zmowa maszyn ;)
Tak sądzę :))))
Edit: a może odpowiedź jest prostsza, niż myślimy? Może po prostu Bill zapomniał o klasie Book? :)))))))))))))))))Piotr Głudkowski edytował(a) ten post dnia 07.08.11 o godzinie 00:27

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

.Ten post został edytowany przez Autora dnia 09.08.16 o godzinie 21:47

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

.Ten post został edytowany przez Autora dnia 09.08.16 o godzinie 21:47

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

Nie. Dokumentacja jest głównym repozytorium wiedzy o projekcie na wszystkich jego płąszczyznach technologicznych i we wszystkich obszarach funkcjonalnych.

Proszę o jakiś precyzyjniejszy opis (duży współczynnik signal/noise ;)
Tu chodzi o możliwość odtworzenia warunków początkowych: wyobraźmy sobie, że jesteś kimś tam w projekcie, masz określone kompetencje, otrzymałeś dokumentację z wcześniejszych faz projektu i jesteś w stanie znaleźć w niej wszystko, co dotyczy Twojej pracy w tym projekcie.
I teraz, nagle na Twoim miejscu pojawia się ktoś inny, o zbliżonych kompetencjach. Chodzi o to, żeby z tych samych kwitów mógł się dowiedzieć wszystkiego, co wiedziałeś Ty (oczywiście mowa o wiedzy niezbędnej do pracy na danym etapie projektu).

Oczywiście to prawda. Chodzi tylko o to, żeby ta osoba mogła przyswoić tą wiedzę z minimalnym nakładem pracy.

Ostatecznie program może nie mieć dokumentacji i może być napisanym w assemblerze (na jakąś konającą architekturę) - z czegoś takiego też można uzyskać wiedzę o 'warunkach początkowych' (bo przecież program wynika tylko z 'warunków początkowych')

Poza tym, czy znajomość ‘warunków początkowych’ jest wystarczająca np. do rozwijania i utrzymania programu ?
A może inaczej; załóżmy konkretną sytuację: PM ma dokumentację (i tylko ją, implementacja jeszcze nie wystartowała) z dokładnie opisaną domeną (analityk) i architekturą. Do czego taka dokumentacja może posłużyć PM'owi ?
Cholera wie :) A poważniej - zależy od organizacji przyjętej podczas prowadzenia projektu.

No właśnie. Dokumentacja ma niejako być dostosowana do organizacji pracy w projekcie.

Dobra zawsze będzie ‘dokładna i kompletna’ ale to, że jakaś dokumentacja będzie użyteczna w danej organizacji pracy nie oznacza tego, że będzie użyteczna w innej (przynajmniej potencjalnie).
Inna sytuacja: do czego taka dokumentacja może przydać się 'innej firmie' przy implementacji nowej funkcjonalności X (zakładam, że wiersza wersja systemu została wdrożona i działa).
Do niczego :) Przecież nie powinniśmy być samobójcami: jeśli klient chce, żeby ktoś inny (tańszy?) mu rozbudowywał projekt, zabierając nasze (potencjalnie) $$$, to chyba nie będziemy mu w tym pomagać zbytnio ?

Myślę, że najlepszym sposobem na utrzymanie klienta jest oferowanie wysokiej jakości w ‘dobrej’ cenie ;)
Czy można jakoś zmierzyć jakość (użyteczność) dokumentacji ?
Czy można zmierzyć pogodę? Czy można zmierzyć sympatię?
Czy to mam odpowiedzieć przełożonemu, kiedy mnie zapyta, czy na podstawie danej dokumentacji, 'mój' zespół jest w stanie stworzyć system ?
Możesz :) A poważniej: jeśli liderzy zespołu, po zapoznaniu się z tym, co napisałeś stwierdzą, że im to wystarczy, to masz już odpowiedź.

No nie do końca bo oni też muszą mieć do tego jakieś podstawy. ‘Dla projektu’ nie ma znaczenia kto (‘ja’ czy ‘oni’) będzie w tej kwestii zgadywać.
W sumie przychodzi mi do głowy jedna rzecz – testy. Taką dokumentacje można przetestować. Tak samo jak program / kod.
Nie do końca. Od tych ludzi wymaga się pewnych kompetencji
Tutaj się w 100% zgadzam.
Ale ludzie są ludźmi, i zawsze lepiej im się czyta coś, co przygotowane zostało dla nich.

Ale nie dla ich roli jaką mają pełnić w zespole. Wyobraź Sobie sytuację, kiedy kierownikowi budowy wręcza się, zamiast rysunku technicznego, słowny opis budynku jaki ma postawić ... Specjalizacja (podział pracy na role) pociąga za sobą potrzebę specjalizowania używanych ‘narzędzi’. Dotyczy to jakże języka.

Jeśli dokumentacja ma formę prozy (nawet na potrzeby 'wewnętrzne') to IMHO zachodzi podejrzenie, że zespół który realizuje projekt nie bardzo zna się na swojej pracy.
Piotr Głudkowski

Piotr Głudkowski Rzucam się na
wszystko to, co jest
ciekawe i wymaga
rusze...

Temat: A ja się dziwię programistom, przepraszam Was...

Jakub Wojt:
/.../

Poza tym, czy znajomość ‘warunków początkowych’ jest wystarczająca np. do rozwijania i utrzymania programu ?

Oczywiście że nie jest wystarczająca. Ale jest niezbędna.
No właśnie. Dokumentacja ma niejako być dostosowana do organizacji pracy w projekcie.

Dobra zawsze będzie ‘dokładna i kompletna’ ale to, że jakaś dokumentacja będzie użyteczna w danej organizacji pracy nie oznacza tego, że będzie użyteczna w innej (przynajmniej potencjalnie).

W 100% się zgadzam.
Inna sytuacja: do czego taka dokumentacja może przydać się 'innej firmie' przy implementacji nowej funkcjonalności X (zakładam, że wiersza wersja systemu została wdrożona i działa).
Do niczego :) Przecież nie powinniśmy być samobójcami: jeśli klient chce, żeby ktoś inny (tańszy?) mu rozbudowywał projekt, zabierając nasze (potencjalnie) $$$, to chyba nie będziemy mu w tym pomagać zbytnio ?

Myślę, że najlepszym sposobem na utrzymanie klienta jest oferowanie wysokiej jakości w ‘dobrej’ cenie ;)

Oczywiście :)
Co nie znaczy, że trzeba ułatwiać konkurencji przejęcie naszego produktu - oczywiście jeśli mamy pole do manewru: jeśli klient zarządał szczegółowej dokumentacji (włącznie z opisem 'flaków') i podjęta została decyzja, że mu ją dostarczamy, to mu ją dostarczamy i już :) Ale, jeśli nie musimy, to po co?
Czy można jakoś zmierzyć jakość (użyteczność) dokumentacji ?
Czy można zmierzyć pogodę? Czy można zmierzyć sympatię?
Czy to mam odpowiedzieć przełożonemu, kiedy mnie zapyta, czy na podstawie danej dokumentacji, 'mój' zespół jest w stanie stworzyć system ?
Możesz :) A poważniej: jeśli liderzy zespołu, po zapoznaniu się z tym, co napisałeś stwierdzą, że im to wystarczy, to masz już odpowiedź.

No nie do końca bo oni też muszą mieć do tego jakieś podstawy.

Ależ tak. Dlatego napisałem 'liderzy', a nie 'kierownik projektu'.
Lider powiniem mieć kompetencje merytoryczne nie niższe (a przynajmniej nie niższe w sposób istotny), niż członkowie jego zespołu.
Ale ludzie są ludźmi, i zawsze lepiej im się czyta coś, co przygotowane zostało dla nich.

Ale nie dla ich roli jaką mają pełnić w zespole. Wyobraź Sobie sytuację, kiedy kierownikowi budowy wręcza się, zamiast rysunku technicznego, słowny opis budynku jaki ma postawić ... Specjalizacja (podział pracy na role) pociąga za sobą potrzebę specjalizowania używanych ‘narzędzi’. Dotyczy to jakże języka.

Jeśli dokumentacja ma formę prozy (nawet na potrzeby 'wewnętrzne') to IMHO zachodzi podejrzenie, że zespół który realizuje projekt nie bardzo zna się na swojej pracy.

Troszkę przejaskrawiłeś. Mi nie chodziło o tworzenie beletrystyki, ale o uniknięcie przypadków, w których forma dokumentacji staje się ważniejsza niż jej treść - a takich przypadków znam sporo.

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

Poza tym, czy znajomość ‘warunków początkowych’ jest wystarczająca np. do rozwijania i utrzymania programu ?

Oczywiście że nie jest wystarczająca. Ale jest niezbędna.

Dlaczego ? Proszę o konkretną odpowiedź :)
.. i wiem, że to pytanie można zinterpretować jako 'poniżej pasa' :)
Do niczego :) Przecież nie powinniśmy być samobójcami: jeśli klient chce, żeby ktoś inny (tańszy?) mu rozbudowywał projekt, zabierając nasze (potencjalnie) $$$, to chyba nie będziemy mu w tym pomagać zbytnio ?

Myślę, że najlepszym sposobem na utrzymanie klienta jest oferowanie wysokiej jakości w ‘dobrej’ cenie ;)

Oczywiście :)
Co nie znaczy, że trzeba ułatwiać konkurencji przejęcie naszego produktu

Produkt przejmuje klient bo jest jego właścicielem :)
Hm ... Właściwie to zależy od tego czy w umowie zapisano 'możliwość rozwoju systemu przez inny zespół'. Z drugiej strony istnieje coś takiego jak 'realizacja projektu zgodnie ze sztuką'... No i jest jeszcze ten Agile który formalnie jest metodyką (sztuką) a pozwala na dowolne skopanie projektu...

Nie wiem ;)
- oczywiście jeśli mamy pole do manewru: jeśli klient zarządał szczegółowej dokumentacji

'dokładnej i kompletnej'
... kurcze, zawsze takiej chcą ;)
(włącznie z opisem 'flaków') i podjęta została decyzja, że mu ją dostarczamy, to mu ją dostarczamy i już :) Ale, jeśli nie musimy, to po co?

Dobre pytanie ...

Bo produkt z pewnością zawiera jakieś błędy które trzeba będzie usunąć...

Nie wiem, zgaduję. :)
Możesz :) A poważniej: jeśli liderzy zespołu, po zapoznaniu się z tym, co napisałeś stwierdzą, że im to wystarczy, to masz już odpowiedź.

No nie do końca bo oni też muszą mieć do tego jakieś podstawy.

Ależ tak. Dlatego napisałem 'liderzy', a nie 'kierownik projektu'.
Lider powiniem mieć kompetencje merytoryczne nie niższe (a przynajmniej nie niższe w sposób istotny), niż członkowie jego zespołu.

Powinien mieć takie które pozwolą mu na realizację zadań.

Jak rozumiem, na pytanie 'jak mierzyć jakość dokumentacji' znają odpowiedź tylko liderzy i jest to wiedza tajemna ;)
Piotr Głudkowski

Piotr Głudkowski Rzucam się na
wszystko to, co jest
ciekawe i wymaga
rusze...

Temat: A ja się dziwię programistom, przepraszam Was...

Jakub Wojt:
Poza tym, czy znajomość ‘warunków początkowych’ jest wystarczająca np. do rozwijania i utrzymania programu ?
Oczywiście że nie jest wystarczająca. Ale jest niezbędna.
Dlaczego ? Proszę o konkretną odpowiedź :)
>
Głównie po to, żeby wyjaśnić przyczyny, dla których na kolejnych etapach projektu podjęto takie, a nie inne decyzje.
Oczywiście warunki początkowe mogą ewoluować: czas idzie do przodu, technologie się zmieniają, koncepcja klienta co do wykorzystania naszego systemu również się zmienia - tak więc niektóre warunki początkowe mogą się dezaktualizować, "umierać". Ale nawet w takich sytuacjach wiedza o tym, dlaczego i kiedy dane warunki umarły stanowi dokumentację historii projektu.
Uczestniczyłem kilka razy w projektach, w których jakieś corowe wymagania umarły i przestały być rozwijane - po czym klient, zmuszony oczekiwaniami rynku, musiał do nich wrócić, i był zdziwiony, dlaczego to nie działa (a dwa lata temu działało).
Takie decyzje muszą być podejmowane odpowiedzialnie, a więc również muszą być udokumentowane (choćby jako CR).

>
Do niczego :) Przecież nie powinniśmy być samobójcami: jeśli klient chce, żeby ktoś inny (tańszy?) mu rozbudowywał projekt, zabierając nasze (potencjalnie) $$$, to chyba nie będziemy mu w tym pomagać zbytnio ?

Myślę, że najlepszym sposobem na utrzymanie klienta jest oferowanie wysokiej jakości w ‘dobrej’ cenie ;)

Oczywiście :)
Co nie znaczy, że trzeba ułatwiać konkurencji przejęcie naszego produktu

Produkt przejmuje klient bo jest jego właścicielem :)
Hm ... Właściwie to zależy od tego czy w umowie zapisano 'możliwość rozwoju systemu przez inny zespół'. Z drugiej strony istnieje coś takiego jak 'realizacja projektu zgodnie ze sztuką'...
Ja to widzę troszkę prościej: jeśli w warunkach kontraktu jest przekazanie kodów źródłowych i przeniesienie praw autorskich (za co klient musi zapłacić oczywiście) - wtedy proszę bardzo: dokumentacja kodu, diagramy klas itd itp.
Ale jeśli tworzymy produkt zamknięty (bo tak stanowi kontrakt) to nie jest absolutnie w naszym interesie przekazywanie jakiejkolwiek wiedzy, ułatwiającej klientowi/konkurencji rozwijanie produktu bez naszego udziału.
No i jest jeszcze ten Agile który formalnie jest metodyką (sztuką) a pozwala na dowolne skopanie projektu...
Co do Agile - nie wypowiem się tutaj, bo mógłbym się komuś narazić :) Mam swoje zdanie na ten temat ;)
- oczywiście jeśli mamy pole do manewru: jeśli klient zarządał szczegółowej dokumentacji
'dokładnej i kompletnej'
... kurcze, zawsze takiej chcą ;)
Ale nie zawsze im się należy :) Jak pisałem wyżej: nie dostanie dokumentacji dot. szczegółów implementacyjnych jesli nie kupił kodów źródłowych.
(włącznie z opisem 'flaków') i podjęta została decyzja, że mu ją dostarczamy, to mu ją dostarczamy i już :) Ale, jeśli nie musimy, to po co?
Dobre pytanie ...
Bo produkt z pewnością zawiera jakieś błędy które trzeba będzie usunąć...

Nie wiem, zgaduję. :)
>
Od tego jest umowa serwisowa, którą klient podpisuje Z NAMI! A jak nie chce, to niech się buja - będzie płacił za konkretne case-y.
Możesz :) A poważniej: jeśli liderzy zespołu, po zapoznaniu się z tym, co napisałeś stwierdzą, że im to wystarczy, to masz już odpowiedź.

No nie do końca bo oni też muszą mieć do tego jakieś podstawy.

Ależ tak. Dlatego napisałem 'liderzy', a nie 'kierownik projektu'.
Lider powiniem mieć kompetencje merytoryczne nie niższe (a przynajmniej nie niższe w sposób istotny), niż członkowie jego zespołu.

Powinien mieć takie które pozwolą mu na realizację zadań.
>
No i to jest przyczyna niepowodzenia wielu projektów - ktoś, kto zarządza MERYTORYCZNIE zespołem, nie rozumie, co ten zespół tak naprawde robi.
Lider zespołu (np. starszy programista) to stanowisko techniczne, a nie menadżerskie. On ma podejmować decyzje (być może z zespołem, to zależy), jak coś zrobić i ile to zajmie, a nie na kiedy i za ile $$$ - od tego jest project manager, product manager i cała kupa ludzi, którym bardzo często wydaje się, że kasa należy im się za funkcję, a nie za robotę :)

Jak rozumiem, na pytanie 'jak mierzyć jakość dokumentacji' znają odpowiedź tylko liderzy i jest to wiedza tajemna ;)
>
Nie. Ale: czy nie znając się na sztuce jesteś w stanie ocenić obraz, namalowany przez artystę? Jasne, mozesz powiedzieć, że fajny kolor tła, no i laska na obrazie niebrzydka - ale czy to jest ocena?
Z drugiej strony: spróbuj sformalizować sposób oceny takiego obrazu w takim stopniu, żeby dawało to się robić algorytmicznie.
Ja myślę, że tutaj winne jest coś innego: menadżerowie, którzy weszli w branżę IT z branż typu piekarnie, fabryki samochodów, zakłady tekstylne :) bardzo by chcieli 'produkować' oprogramowanie. I tu jest problem, bo akurat programowanie, podobnie jak sztuka, produkować się nie daje, bo jest w 100% pracą twórczą, a nie odtwórczą. Tak więc pojęcia i metodyki, stosowane w typowych zakładach produkcyjnych tutaj się bardzo słabo sprawdzają.
A co do automatycznej oceny jakości dokumentacji:
Ja wiem, że programiści, a ogólnie IT-mani (ci, którzy tworzą), chcieliby móc zaprogramować wszystko (łącznie z żoną - też bym chciał) i stąd biorą się próby tworzenia automatów oceniających jakość kodu czy jakość dokumentacji.
Ale tak naprawdę musimy przyznać: różne firmy stosują różne metody oceny kodu - ale każdą można wyśmiać. To samo się tyczy dokumentacji. Możesz policzyć ilość kartek, wierszy, liter, spacji. Możesz sprawdzić, czy nazwa każdego pola z tabel w bazie występuje minimum raz w dokumencie. Ale nie sprawdzisz automatem tego, czy dokumentacja napisana jest logicznie i czy da się z niej korzystać.
Przez słowo 'automatycznie', które użyłem powyżej, rozumiem nie tyle sprawdzanie przez specjalizowane oprogramowanie, ale również sprawdzanie przez zestaw reguł: począwszy od metodyki, poprzez zalecane layouty itd.
Czy ta wiedza jest tajemna? Nie. Wymaga przeczytania dokumentacji ZE ZROZUMIENIEM i jej oceny. Wiem, że to trudne i coraz mniej ludzi posiada taki dar :)Piotr Głudkowski edytował(a) ten post dnia 11.08.11 o godzinie 13:35

konto usunięte

Temat: A ja się dziwię programistom, przepraszam Was...

Poza tym, czy znajomość ‘warunków początkowych’ jest wystarczająca np. do rozwijania i utrzymania programu ?
Oczywiście że nie jest wystarczająca. Ale jest niezbędna.
Dlaczego ? Proszę o konkretną odpowiedź :)
>
Głównie po to, żeby wyjaśnić przyczyny, dla których na kolejnych etapach projektu podjęto takie, a nie inne decyzje.

W kontekście jakiej metody (standardu) realizacji projektu takie decyzje są ważne (ustaliliśmy, że 'jakość' dokumentacji zależy od procesu realizacji projektu) ?

Podejrzewam, że takiej metody (nie wspominając o wyjaśnieniu sensu ww. czynności) póki co nie ma.

Ogólnie - nie ma żadnego standardu dla dokumentacji IT bo nie ma żadnego standardu realizacji projektu IT (no może poza Cleanroom (http://en.wikipedia.org/wiki/Cleanroom_Software_Engine... ).

Z tego samego powodu nie ma miary jakości (w kontekście metody realizacji projektu) samej dokumentacji.

Pytanie "po co jest dokumentacja" jest de facto pytaniem o standard realizacji projektu. Na pytanie „Po co jest UML” można odpowiedzieć tylko wtedy, kiedy się wie, co po tworzy się dokumentację.

Można stworzyć model realizacji projektu IT i na jego podstawie określić wymagany rodzaj i jakość (miara) dokumentacji.

Przykład (wymyślony na poczekaniu więc proszę się czepiać tylko bzdur skrajnych ;) jak mógłby taki proces wyglądać:

Podział ról: analityk, projektant GUI, projektant architektury, programista.

Etap 1: Analiza
Zadaniem analityka jest zdefiniowane domeny problemu. Efektem jego pracy są

- Dokument (w formie cyfrowej) na podstawie którego można wygenerować kod funkcjonalności biznesowej aplikacji czyli np. diagram klas (może być UML) w którym typy atrybutów są 'biznesowe' i zdefiniowane (chodzi o ograniczenia - user_name to nie jest 'string' bo user_name nie może być np. pusty).
Podobnie z metodami biznesowym – maja być określone na obiektach domeny (use case'y to metody publiczne na klasach obiektów domeny) i zdefiniowane za pomocą jakiegoś formalnego języka (np. coś w rodzaju 'basica').

- Definicje testów jednostkowych (formalny język) i zbiory danych testowych na jakich ww. testy mają zostać przeprowadzone.
Testy jednostkowe można definiować jako krotki: stan 'wejściowy' systemu, operacja, oczekiwany stan wyjściowy systemu (wynik).

Miarą jakości tej części dokumentacji jest:
- to czy stworzony przez niego model jest spójny i kompletny (są programy które potrafią to weryfikować)
- stopień pokrycia funkcjonalności przez testy jednostkowe, ilość i 'stopień różnorodności' zbiorów danych testowych.

Na podstawie takiego modelu można generować:
- kod warstwy 'biznesu' (klasy + interfejsy) programu
- kod testów jednostkowych dla funkcjonalności biznesowej.
- schemat bazy danych

Etap 2: Projekt GUI
Zadaniem projektant GUI jest stworzenie widoków(przepływów) do realizacji funkcjonalności biznesowej. Dokumentacja od analityka dostarcza mu wszystkich potrzebnych informacji czyli listę przypadków użycia (publiczne metody z klas) i parametry jakie użytkownik musi podać żeby je wywołać.
Efektem jego pracy jest dokument zawierający listę widoków (klasy formsów / paneli / dedykowanych kontrolek) 'podpiętych' do modelu biznesowego wraz z zdefiniowanymi przepływami.
Całość oczywiście w jakimś formalnym języku do opisu GUI :)

Na podstawie ww. dokumentu można generować warstwę View + Controler aplikacji.

Miara jakości:
- ergonomia GUI (opinia Pani Jadzi ;)
- brak błędów GUI podczas wywoływania na nich testów jednostkowych modelu.

Etap 3: Architektura
Architekt - analogicznie jak analityk tylko że dla warstwy integracji warstwy biznesowej z fizyczną.
Tworzy harmonogram implementacji.

Etap 4: Implementacja (o ile coś do zaimplementowania zostało)
Progrmista - implementuje to, co zadokumentował architekt w danej technologii. Nie tworzy dokumentacji.

Jak widać (?), jeśli ma się 'model procesu' to można dla niego stworzyć szablon dokumentacji z określoną miarą jakości.

Inną sprawą jest to, czy jest to skuteczny 'model procesu'...Jakub Wojt edytował(a) ten post dnia 16.08.11 o godzinie 11:48
Aleksander Olszewski

Aleksander Olszewski Kierownik Projektów
IT, PRINCE2
Practitioner

Temat: A ja się dziwię programistom, przepraszam Was...

Jakub Wojt:
...
Etap 1: Analiza
...
Etap 2: Projekt GUI
Zadaniem projektant GUI jest stworzenie widoków(przepływów) do realizacji funkcjonalności biznesowej. Dokumentacja od analityka dostarcza mu wszystkich potrzebnych informacji czyli listę przypadków użycia (publiczne metody z klas) i parametry jakie użytkownik musi podać żeby je wywołać.
Efektem jego pracy jest dokument zawierający listę widoków (klasy formsów / paneli / dedykowanych kontrolek) 'podpiętych' do modelu biznesowego wraz z zdefiniowanymi przepływami.
Całość oczywiście w jakimś formalnym języku do opisu GUI :)

Na podstawie ww. dokumentu można generować warstwę View + Controler aplikacji.

Miara jakości:
- ergonomia GUI (opinia Pani Jadzi ;)
- brak błędów GUI podczas wywoływania na nich testów jednostkowych modelu.

Jak dla mnie, to tu jest podstawowy błąd :) Dlaczego GUI powstaje przed architekturą i implementacją funkcjonalności czysto biznesowych? Czy mamy spędzić 2 miesiące na przesuwaniu loga, a potem w 2 tygodnie wydziergać całą aplikację? Wedle mnie to architektura i logika determinuje GUI, a nie odwrotnie. Stosując MVC bez problemu wystylizujemy warstwę widoku. Taka kolejność ogranicza pole manewru już na samym początku projektu.

Ponadto Pani Jadzia powinna być decyzyjna w swoim zakresie. Znany jest taki przypadek, gdy Pani Jadzia Szef zleciła dodanie mrugającego loga do aplikacji: każdy pracownik nie może zapomnieć dla kogo pracuje. Szybko trzeba było wprowadzać kolejne zmiany --- nikt nie mógł wytrzymać 8 godz. z takim logo. Są też obiektywne metryki ergonomii, wynikające ze statystycznego rozkładu elementów różnych aplikacji.
Etap 3: Architektura
...
Etap 4: Implementacja (o ile coś do zaimplementowania zostało)
...

Inną sprawą jest to, czy jest to skuteczny 'model procesu'...

To co tu opisujesz jest typowym podejściem wodospadowym. Nie jest to ani wydajne, ani produktywne. Poza tym moim zdaniem kolejność jest do zmiany :)



Wyślij zaproszenie do