wtorek, 25 czerwca 2013

Oznaczanie zmian pomiędzy wersjami generowanych dokumentów

Dokumentacja projektowa powstaje zazwyczaj iteracyjnie. Czyli najpierw powstaje pierwsza wersja dokumentu, która jest opiniowana. Zgłoszone uwagi do dokumentu są uwzględniane przez autora (autorów) i w odpowiedzi powstaje druga wersja dokumentu i tak dalej... W innym scenariuszu, gdy dokument opisuje działający system informatyczny - zawartość dokumentów zmienia się wraz z wprowadzanymi modyfikacjami do systemu.
Gdy opisywane rozwiązanie jest małe, wówczas adresaci dokumentacji mają szanse się orientować dokładnie w zawartości dokumentów. Jednak, gdy dokumentacja dotyczy dużego i złożonego systemu, wówczas rodzi się potrzeba odpowiedniego oznaczania zmian w dokumentacji. Dzięki takim oznaczeniom osoby, które opiniują dokument mogą ograniczyć się na przykład do opiniowania tylko i wyłącznie treści dodanych lub zmienionych w odniesieniu do ostatniej wersji.

Jeśli dokumentacja projektowa powstaje wprost w MS Office, wówczas najlepszym sposobem na oznaczanie zmian pomiędzy wersjami wydaje się:

  • zastosowanie Trybu Rejestracji Zmian (ang. Track Changes),
  • lub oznaczanie kolorami dodanego tekstu oraz przekreślanie tekstu usuniętego.
Jeśli jednak zespół w trosce o poprawę jakości generowanej dokumentacji i ograniczenie pracochłonności, decyduje się na generowanie dokumentacji projektowej z narzędzia Enterprise Architect - wówczas wykorzystanie Trybu Rejestracji Zmian nie jest możliwe.

Co można zrobić w takiej sytuacji?

Sprowadza się ono do wygenerowania nowej wersji dokumentu, wskazania na dysku poprzedniej wersji dokumentu, a następnie porównania obu wersji w MS Word przy użyciu funkcji Compare, dzięki czemu może powstać nowy dokument wzbogacony o różnice między dwiema wersjami.
Proces ten przedstawia poniższy diagram aktywności.
track changes in EA generated reports

Proces ten można z powodzeniem stosować w przypadku generowania małej ilości dokumentacji przez wyznaczone osoby, które sprawnie to obsłużą.

Jednakże, gdy mamy do czynienia z generowaniem wielokrotnie dużej ilości dokumentacji i działamy pod presją czasu, wówczas przydałby się plugin, dzięki któremu możliwe byłoby przyspieszenie tych operacji i zminimalizowanie wystąpienia błędów (np. polegających na porównaniu niewłaściwych wersji dokumentów).

Przykład takiego pluginu można znaleźć w prezentacji projektu DEEWR (opisanego przeze mnie niedawno we wpisie Przykład zastosowania EA - projekt z Australii)
Plugin ten obsługuje proces generowania zdefiniowanych dokumentów i posiada również możliwość porównania (Comparison Report) z inną wersją dokumentu lub innym dokumentem. Plugin ten posiada wiele innych opcji, wśród których można znaleźć na przykład możliwość porównania również z innym raportem generowanym wprost z repozytorium EA, czy oznaczania jako zmienione tylko elementy zmodyfikowane po wskazanej dacie.

Niniejszy wpis ma za zadanie jedynie wskazanie metody rozwiązania problemu i może stanowić inspirację do samodzielnego stworzenia pluginu o podobnej funkcjonalności.

2 komentarze:

  1. wlasnie szukalem coś na ten temat, a tu proszę:)
    czy mogę prosić o artykuły na temat pracy grupowej i wersjonowania modeli - szczególnie mnie interesuje praktyczne podejście.
    ponadto szukam jakiegos dobrego pluginu do zarządzania wymaganiami (m.in. walidacja wymagań) - czy mógłbyś coś polecić?

    OdpowiedzUsuń
  2. Mam w planach kolejne artykuły o pracy grupowej, które będą prezentować praktyczne podejście do tematu.

    Jeśli chodzi o plugin do zarządzania wymaganiami to istnieje Raquest (www.raquest.com), który korzysta z repozytorium EA (EAP lub baza danych) i udostępnia interfejs użytkownika dostosowany do pracy z wymaganiami a nie do modelowania.
    Jeśli chodzi o walidację wymagań - to najlepiej dostosować zakres walidacji do wymagań projektowych. Można spróbować się oprzeć np. na EnArValidationRules (blog.lieberlieber.com/2013/04/11/enarvalidationrules-validate-and-auto-correct-your-enterprise-architect-models/) lub samemu stworzyć zapytania SQL i/lub skrypty do walidacji.

    OdpowiedzUsuń