Temat: Zrozumiałość diagramów

Czy diagramy UML (ogólniej - dokumentacja) muszą być zrozumiałe ?
Jeśli tak - czym jest owa "zrozumiałość" i jak ją mierzyć ?

Czy istnieją "współczynniki zrozumiałości" na podstawie których można stwierdzić, że dany zestaw diagramów jest "zrozumiały" ?

Temat: Zrozumiałość diagramów

Jakub Wojt:
Czy diagramy UML (ogólniej - dokumentacja) muszą być zrozumiałe ?

Tak na poważnie zadajesz to pytanie? Bo odpowiedź na nie jest tak oczywista, że nie wiem czy nie usiłujesz tu jakiejś prowokacji zrobić... :)Jacek Sałacki edytował(a) ten post dnia 02.03.11 o godzinie 10:24

Temat: Zrozumiałość diagramów

Jakub Wojt:
Czy diagramy UML (ogólniej - dokumentacja) muszą być zrozumiałe ?

Tak na poważnie zadajesz to pytanie? Bo odpowiedź na nie jest tak oczywista, że nie wiem czy nie usiłujesz tu jakiejś prowokacji zrobić... :)Jacek Sałacki edytował(a) ten post dnia 02.03.11 o godzinie 10:24

Oczywiście, że na poważnie. :)
Jeśli dobrze rozumiem - Pańska odpowiedź jest twierdząca...
Proszę w takim razie o odpowiedź na pozostałe pytania :)

.. i w sumie jeszcze jedno - czy powinniśmy oceniać jakość czegokolwiek na podstawie pojęć których nie można jasno zdefiniować ?

Temat: Zrozumiałość diagramów

Można spróbować sobie takie zdefiniować :-)
Na przykład:

Jeśli diagram zarówno dla autora tego diagramu, jak i odbiorcy / adresata (czytającego ten diagram) oznaczają to samo, to można chyba powiedzieć, że jest on dla tych dwóch osób zrozumiały :-)

Czy będzie on (i czy musi być) zrozumiały dla innych osób, to już osobna kwestia... :-)

Temat: Zrozumiałość diagramów

Jakub Wojt:
Czy diagramy UML (ogólniej - dokumentacja) muszą być zrozumiałe ?
Jeśli tak - czym jest owa "zrozumiałość" i jak ją mierzyć ?

Czy istnieją "współczynniki zrozumiałości" na podstawie których można stwierdzić, że dany zestaw diagramów jest "zrozumiały" ?

Oczywiście. To metoda komunikacji i jako taka poddaje się wszelkim związanym z tym prawom. Jeśli przyjmiemy, że
A - model rzeczywisty
a - percepcja modelującego
a~ - zapis percepcji jako model UML
a' - percepcja czytającego model
A' - model wykonany(wyobrażony) na podstawie projektu przez odbiorcę
to przedtawienie koncepcji z wykorzystaniem UML wygląda tak
A->a->a~->a'->A'
w takim przekształceniu wszelkie różnice między a <-> a' to błędy wynikające z przekłamań modelu, czyli:
- błędnej semantyki, syntaktyki modelu
- odmiennej pragmatyki modelującego i odbiorcy - może znają język modelowania w różnym stopniu, może jeden zna a drugi tylko "intuicyjnie odczytuje"
wszeldkie różnice między A <-> A' to suma powyżej opisanego błędu i błędu wnioskowania. Jeśli więc błąd a <-> a' jest nie wielki - oznacza to, że sam model uczestnicy komunikacji postrzegają podobnie, ale w inny sposób go wizualizują - tutaj dochodzą bardzo indywidualne kwestie doświadczenia. Za przykład niech posłuży fakt z USA. Gdy w klasie powiedziano dzieciom narysujcie rybę - wszyscy zrozumieli to samo. Wiedzą co to ryba, ale niemal połowa narysowała prostokąt - bo całe życie widziała tylko filet na talerzu.

Temat: Zrozumiałość diagramów

Jakub Wojt:

Jakub Wojt:
Czy diagramy UML (ogólniej - dokumentacja) muszą być zrozumiałe ?

Tak na poważnie zadajesz to pytanie? Bo odpowiedź na nie jest tak oczywista, że nie wiem czy nie usiłujesz tu jakiejś prowokacji zrobić... :)Jacek Sałacki edytował(a) ten post dnia 02.03.11 o godzinie 10:24

Oczywiście, że na poważnie. :)
Jeśli dobrze rozumiem - Pańska odpowiedź jest twierdząca...

Może na początek zrezygnujemy z "panowania" sobie :)

Proszę w takim razie o odpowiedź na pozostałe pytania :)

Koledzy powyżej już odpowiedzieli, trochę sarkastycznie co prawda ...

.. i w sumie jeszcze jedno - czy powinniśmy oceniać jakość czegokolwiek na podstawie pojęć których nie można jasno zdefiniować ?

Tak bardziej na poważnie, dwie kwestie:
1. Jak sobie wyobrażasz dokumentację, która nie będzie zrozumiała? To po co ona jest?
2. Używasz pojęcia "jakość" - jak w takim razie definiujesz to pojęcie? Jak je mierzysz? Jak oceniasz pomiar? Zawsze jest to proste i oczywiste?

Już całkowicie merytorycznie odpowiadając wprost na pytanie: nie da rady zmierzyć wprost zrozumiałości, ale możesz ją ocenić.
Po przeczytaniu dowolnej książki, artykułu obejrzeniu filmu jesteś w stanie powiedzieć czy przekaz był dla ciebie zrozumiały, prawda? I to jest właśnie kluczowe komu, co i w jaki sposób przekazujesz.

Niestety dla ciebie, nie ma oczywiście żadnych przepisów jak zrobić zrozumiałą dokumentację (czy model UML), tak jak nie ma recepty jak napisać dobrą książkę czy zrobić dobry film. To niestety jest element sztuki :P

Temat: Zrozumiałość diagramów

Jacek Sałacki:
Już całkowicie merytorycznie odpowiadając wprost na pytanie: nie da rady zmierzyć wprost zrozumiałości, ale możesz ją ocenić.

Pozwolę sobie polemizować.

Jak nie można czegoś zmierzyć to jak można oceniać? Ocena to pewien wniosek z pomiaru. Sprawdzasz sprawdzian, porównujesz wyniki ze wzorcem, z innymi i go oceniasz - ten model się przekłada. Pomiar nie zawsze musi być obiektywny czy z określoną skalą (vide ocena eseju w szkole) ale jest dokonywany. Oczywiście najlepiej go formalizować.

Po przeczytaniu dowolnej książki, artykułu obejrzeniu filmu jesteś w stanie powiedzieć czy przekaz był dla ciebie zrozumiały, prawda? I to jest właśnie kluczowe komu, co i w jaki sposób przekazujesz.

No nie. Daj dziecku do przeczytania potop nie mówiąc nic o rozbiorach i opowie Ci zupełnie inną historię.

Niestety dla ciebie, nie ma oczywiście żadnych przepisów jak zrobić zrozumiałą dokumentację (czy model UML), tak jak nie ma recepty jak napisać dobrą książkę czy zrobić dobry film. To niestety jest element sztuki :P

Przeciwnie - są - przede wszystkim jest to poprawność językowa modelu, a dalej dobra pragmatyka - czyli stosowanie wzorców projektowych, trzymanie się stałego poziomu abstrakcji, określonej taskonomii, itp. itd.

Temat: Zrozumiałość diagramów

Jakub Wojt:
Czy diagramy UML (ogólniej - dokumentacja) muszą być zrozumiałe ?
Jeśli tak - czym jest owa "zrozumiałość" i jak ją mierzyć ?

Czy istnieją "współczynniki zrozumiałości" na podstawie których można stwierdzić, że dany zestaw diagramów jest "zrozumiały" ?

matematyk pisze furę wzorów w dwóch celach:
- aby przekazać innemu matematykowi swój pomysł
- aby móc z duża pewnością powiedzieć laikowi, że prawdę jest ostateczny wniosek, który wyciągnął

w pierwszym przypadku obaj musza się z równą biegłością posługiwać językiem matematyki, w drugim nie koniecznie.

jeżeli UML będzie językiem komunikacji pomiędzy projektantem a wykonawcą to obaj muszą go znać równie dobrze.

W analizie systemowej pośrednim etapem są modele służące do testowania wariantów i hipotez a końcowym produktem analizy: rekomendacje (nawet proza z zaleceniami). Adresat musi zrozumieć rekomendacje, modeli - tu już nie musi...

Tak wiec UML jest dla adresata zrozumiały bardzo dobrze albo nie jest mu potrzebny. Nie wyobrażam sobie sytuacji w której ktoś tylko "częściowo" zrozumiał np. projekt... a jak sobie wyobrażę to ciarki przechodzą :) Jarek Żeliński edytował(a) ten post dnia 02.03.11 o godzinie 23:16

Temat: Zrozumiałość diagramów

Jarek Żeliński:
Tak wiec UML jest dla adresata zrozumiały bardzo dobrze albo nie jest mu potrzebny. Nie wyobrażam sobie sytuacji w której ktoś tylko "częściowo" zrozumiał np. projekt... a jak sobie wyobrażę to ciarki przechodzą :) Jarek Żeliński edytował(a) ten post dnia 02.03.11 o godzinie 23:16

Tu sobie Jarku nie ma czego wyobrażać, wystarczy odgrzebać korespondencję zamkniętych projektów i koncepcje ich niektórych udziałowców:D

Temat: Zrozumiałość diagramów

:)

Temat: Zrozumiałość diagramów

Po przeczytaniu dowolnej książki, artykułu obejrzeniu filmu jesteś w stanie powiedzieć czy przekaz był dla ciebie zrozumiały, prawda? I to jest właśnie kluczowe komu, co i w jaki sposób przekazujesz.

No nie. Daj dziecku do przeczytania potop nie mówiąc nic o rozbiorach i opowie Ci zupełnie inną historię.

No właśnie... Jak napisałem:

jest właśnie kluczowe komu, co i w jaki sposób przekazujesz.Jacek Sałacki edytował(a) ten post dnia 03.03.11 o godzinie 07:36

Temat: Zrozumiałość diagramów

co nie zmienia faktu, że kształt domu który powstanie na bazie rysunków technicznych nie powinien zależeć od życiorysu murarza....

Temat: Zrozumiałość diagramów

Jacek Sałacki:

Po przeczytaniu dowolnej książki, artykułu obejrzeniu filmu jesteś w stanie powiedzieć czy przekaz był dla ciebie zrozumiały, prawda? I to jest właśnie kluczowe komu, co i w jaki sposób przekazujesz.

No nie. Daj dziecku do przeczytania potop nie mówiąc nic o rozbiorach i opowie Ci zupełnie inną historię.

Kontrargumentowałem jedynie, że nie zawsze potrafisz ocenić, czy przekaz był dla Ciebie zrozumiały. Czasem wydaje Ci się, że tak - a szersze spojrzenie na problem pokazuje zupełnie inny obraz.

No właśnie... Jak napisałem:

jest właśnie kluczowe komu, co i w jaki sposób przekazujesz.Jacek Sałacki edytował(a) ten post dnia 03.03.11 o godzinie 07:36

Ale to na zupełnie inny temat, z dym faktem nie dyskutuję. Ale wniosek z tego taki, że architektowi systemu przekazuję projekt.vpp z pełnymi modelami, a dla biznesu wyciągam 3 najważniejsze procesy, dające największą wartość dodaną w dodatku na najwyższym sensownym poziomie abstrakcji, analogicznie dorzucam diagram przypadków użycia - z zaznaczeniem jedynie tych, które w procesach odpowiadają za kroki zmieniające KPI/tworzące VA, dodaje komentarze, ilustruję bogato przykładami a prezentację MÓWIĘ, a nie wysyłam:)
Model jednak pozostaje ten sam i architekt bynajmniej nie ogląda moich analogii do budownictwa:)

Temat: Zrozumiałość diagramów

Koledzy powyżej już odpowiedzieli, trochę sarkastycznie co prawda ...

... życie :)

.. i w sumie jeszcze jedno - czy powinniśmy oceniać jakość czegokolwiek na podstawie pojęć których nie można jasno zdefiniować ?

Tak bardziej na poważnie, dwie kwestie:
1. Jak sobie wyobrażasz dokumentację, która nie będzie zrozumiała? To po co ona jest?

Po to, żeby jej używać. Programista nie musi "rozumieć" dokumentacji żeby np. implementować hierarchię klas z jakiegoś diagramu.

2. Używasz pojęcia "jakość" - jak w takim razie definiujesz to pojęcie? Jak je mierzysz? Jak oceniasz pomiar? Zawsze jest to proste i oczywiste?

Tak - jakość to stopień w jakim dokumentacja pozwala na realizację celów jakie jej się stawia.

Po przeczytaniu dowolnej książki, artykułu obejrzeniu filmu jesteś w stanie powiedzieć czy przekaz był dla ciebie zrozumiały, prawda? I to jest właśnie kluczowe komu, co i w jaki sposób przekazujesz.

Zgoda. Ale obawiam się, że moja opinia jest dość słabym miernikiem (a zatem nie może przesądzać o) "zrozumiałości". Dokumentacja nie może zostać uznana za "zrozumiałą" nawet jeśli "ja" ją zrozumiem. Ostatecznie zawsze jest przynajmniej jedna osoba która dokumentację rozumie (no, może poza skrajnymi przypadkami) - jej twórca. Ale chyba nie o to chodzi...

Niestety dla ciebie, nie ma oczywiście żadnych przepisów jak zrobić zrozumiałą dokumentację (czy model UML), tak jak nie ma recepty jak napisać dobrą książkę czy zrobić dobry film. To niestety jest element sztuki :P

... to beznadziejnie :) Tworzenie dokumentacji (ogólnie - dokumentowanie) to generalnie kosztowny proces. Jeśli "zrozumienie" jest jednym z mierników jakości to dokumentacja staje się rodzajem "technicznej wróżby"...

Może więc jednak uznać, że dokumentacja nie jest po to, żeby ją "rozumieć" ? A "zrozumiałość" wyrzucić ze zbioru mierników jakości :)

Temat: Zrozumiałość diagramów

Czy istnieją "współczynniki zrozumiałości" na podstawie których można stwierdzić, że dany zestaw diagramów jest "zrozumiały" ?

... Tak wiec UML jest dla adresata zrozumiały bardzo dobrze albo nie jest mu potrzebny. Nie wyobrażam sobie sytuacji w której ktoś tylko "częściowo" zrozumiał np. projekt... a jak sobie wyobrażę to ciarki przechodzą :)

hm.. to diagramy muszą być zrozumiałe, czy nie ?
PS. mnie przechodzą ciarki kiedy (np) programista mówi, że "zrozumiał".
Skoro "rozumie" to znaczy, że potrafi "przewidzieć" ... ergo "wymyślić".
Chyba wszyscy wiedzą jak się kończą "wymyślane; wydedukowane" implementacje...

Temat: Zrozumiałość diagramów

1. Jak sobie wyobrażasz dokumentację, która nie będzie zrozumiała? To po co ona jest?

Po to, żeby jej używać. Programista nie musi "rozumieć" dokumentacji żeby np. implementować hierarchię klas z jakiegoś diagramu.

Ot tu bym się zatrzymał na chwilę, celna uwaga i ważne rozróżnienie:
- rozumienie języka jakim jest UML
- rozumienie projektu

osobiście przychylam się tezy, że programista nie musi rozumieć istoty projektu ale musi rozumieć treść "zamówienia". Musi rozumieć UML żeby implementować jakaś hierarchę klas ale faktycznie już nie musi rozumieć dlaczego ktoś zaprojektował właśnie taką.

Jednak chyba gdzieś prawda leży po środku: murarz nie musi rozumieć tego dlaczego ja chcę mieć piec na środku kuchni ale musi zrozumieć projekt, rysunki, tej kuchni żeby to wykonać. Jednak jest różnica pomiędzy murarzem, któremu trzeba w projekcie to opisać do ostatniego grama gipsu a murarzem, któremu wystarczy na rysunku zaznaczyć, że ścianka maskująca ma być wykonana z płyty gipsowokartonowej.

... to beznadziejnie :) Tworzenie dokumentacji (ogólnie - dokumentowanie) to generalnie kosztowny proces. Jeśli "zrozumienie" jest jednym z mierników jakości to dokumentacja staje się rodzajem "technicznej wróżby"...

o jakie rozumienie chodzi notacji czy istoty udokumentowanego projektu?

Temat: Zrozumiałość diagramów

Jakub Wojt:
Czy diagramy UML (ogólniej - dokumentacja) muszą być zrozumiałe ?

Nie i czasami nie są zrozumiałe zwłaszcza dla Klientów (aczkolwiek miałem przypadki, że programistów trzeba było szkolic z UML). Wtedy stosuje się inne notacje.

Jeśli tak - czym jest owa "zrozumiałość" i jak ją mierzyć ?

Czy istnieją "współczynniki zrozumiałości" na podstawie których można stwierdzić, że dany zestaw diagramów jest "zrozumiały" ?

Rozumiem, że pytanie dotyczy architektury oprogramowania.
Cofnijmy się zatem 36 lat wstecz.
Idea Freda Brooks’a z 1975 r.: „im więcej osób dołącza do pracy w późnej fazie projektu, tym później ukazuje się on na rynku”. Zasada ta charakteryzowała czasy, gdy architektura oprogramowania była jeszcze w „powijakach” i zmiany w zespołach projektowych, bez stosownych modeli oprogramowania, nieraz miewały katastrofalny skutek dla projektu. Nawet dzisiaj błędny projekt architektury może spowodować wycofanie się sponsorów z projektu, co potwierdza jedno z ciekawych stwierdzeń, które SEI podniosło do rangi definicji, którym jest cytat Eoina Woodsa:
„Architektura oprogramowania jest listą decyzji projektowych, które w przypadku nieodpowiedniego wykonania, mogą spowodować anulowanie całego projektu ”. Nieudane projekty zazwyczaj można opisać słowami Jima Archera „Wpierw płacisz za rezultaty, następnie za wysiłek i ostatecznie za obecność ”.
Unikanie nieudanych projektów radzi Barry Boehm w 1995 roku „Dopóki w przedsięwzięciu nie powstała architektura systemu wraz z uzasadnieniem, nie powinno się rozpoczynać tworzenia systemu na pełną skalę. Wyspecyfikowanie architektury oprogramowania w postaci, która pozwala na jej przekazywanie, umożliwia jej stosowanie w procesie tworzenia i pielęgnacji.”.
Natomiast Philippe Kruchten twierdzi w 1998 roku, że architektura oprogramowania wcale nie jest tak skomplikowana, gdyż „Architektura jest tym, co pozostaje, gdy nie można już usunąć niczego więcej, a system ciągle jest zrozumiały i można objaśnić jego działanie.”.
Z drugiej strony Philippe Kruchten zauważył w 2001 roku, że „Gdy proces zanika, zostaje dobra praktyka, Gdy dobra praktyka zanika, istnieją jeszcze reguły, Kiedy reguł brak, pozostaje rytuał, Rytuał zaś jest początkiem chaosu”.

Temat: Zrozumiałość diagramów

>.... Programista nie musi "rozumieć"

dokumentacji żeby np. implementować hierarchię klas z jakiegoś diagramu.
... to beznadziejnie :) Tworzenie dokumentacji (ogólnie - dokumentowanie) to generalnie kosztowny proces. Jeśli "zrozumienie" jest jednym z mierników jakości to dokumentacja staje się rodzajem "technicznej wróżby"...

o jakie rozumienie chodzi notacji czy istoty udokumentowanego projektu?

Chodzi oczywiście o istotę dokumentowanego projektu.
Zadałem to pytanie w kontekście umieszczania opisów UC (scenariuszy) pod diagramami np. sekwencji.

Temat: Zrozumiałość diagramów

Troszkę off-topic :-)

Mateusz Kurleto:

Jacek Sałacki:
Po przeczytaniu dowolnej książki, artykułu obejrzeniu filmu jesteś w stanie powiedzieć czy przekaz był dla ciebie zrozumiały, prawda? I to jest właśnie kluczowe komu, co i w jaki sposób przekazujesz.

No nie. Daj dziecku do przeczytania potop nie mówiąc nic o rozbiorach i opowie Ci zupełnie inną historię.

Wybitnie niefortunne porównanie, aż chce się zapytać "co ma piernik do wiatraka?" :-) Może w odniesieniu do tak istotnych wydarzeń historycznych nie jest to pytanie na miejscu, nie mniej jednak wydarzenia te oddziela od siebie przeszło 100 lat (potop - 1655-1660, I rozbiór Polski - 1772). Mam nadzieję, że nie muszę przypominać, że Szwedzi w rozbiorach udziału nie brali...Jakub Płachecki edytował(a) ten post dnia 06.03.11 o godzinie 20:50

Temat: Zrozumiałość diagramów

Jakub Płachecki:
Troszkę off-topic :-)

Mateusz Kurleto:

Jacek Sałacki:
Po przeczytaniu dowolnej książki, artykułu obejrzeniu filmu jesteś w stanie powiedzieć czy przekaz był dla ciebie zrozumiały, prawda? I to jest właśnie kluczowe komu, co i w jaki sposób przekazujesz.

No nie. Daj dziecku do przeczytania potop nie mówiąc nic o rozbiorach i opowie Ci zupełnie inną historię.

Wybitnie niefortunne porównanie, aż chce się zapytać "co ma piernik do wiatraka?" :-) Może w odniesieniu do tak istotnych wydarzeń historycznych nie jest to pytanie na miejscu, nie mniej jednak wydarzenia te oddziela od siebie przeszło 100 lat (potop - 1655-1660, I rozbiór Polski - 1772). Mam nadzieję, że nie muszę przypominać, że Szwedzi w rozbiorach udziału nie brali...Jakub Płachecki edytował(a) ten post dnia 06.03.11 o godzinie 20:50

Piernik do wiatraka ma tyle, że Sienkiewicz pisał książki "wywrotowe" w czasie rozbiorów opisując sukcesy Polaków w przeszłości. Osoba, która o tym fakcie nic nie wie, czytając Potop pozna jedynie historię najazdu Szwedów, nie znajdując żadnej paraboli do rozbiorów, będzie za to przekonana, że świetnie zrozumiała Powieść, włącznie ze studium charakterów jej głównych bohaterów.
Natomiast faktycznie nie do końca ją rozumie, bo nie zna całego tła historycznego, ze współczesności autora, do którego tenże się odwołuje.
Wniosek z tego taki, że jako odbiorca nie zawsze jesteś w stanie powiedzieć, czy odbiór był dla Ciebie zrozumiały.