Sybena Consulting

Tworzenie tekstów analitycznych

 

Strona główna

Wiedza

Kontakt

Projekty publiczne

Wprowadzenie

Zakres dokumentu

Znakowanie pojęć

Mikrostandardy

Zaawansowane: model rodzajów pojęć

Podsumowanie

Wprowadzenie

Za tekst techniczno–zarządczy można uważać każdy produkt lub półprodukt powstający w trakcie produkcji systemów, nie będący kodem programu ani innym produktem przeznaczonym do wykonania. Przykładem półproduktu nie będącego opracowaniem technicznym i jednocześnie nie będącego kodem programu jest specyfikacja scenariuszy testowych. Przykładami tekstów techniczno – zarządczych są: oferta opisująca system przeznaczony na sprzedaż, plan projektu, specyfikacja systemu (na poziomie biznesowym lub technicznym), projekt architekturalny, czy plan testów.

Wytworzenie opracowania techniczno-zarządczego wymaga zastosowania wiedzy z różnych obszarów. Istnieją trzy zasadnicze obszary wiedzy, konieczne do wykorzystania przy tworzeniu opracowania technicznego:

·         Wiedza dziedzinowa,

·         Metodologia tworzenia systemów,

·         Umiejętność tworzenia tekstów technicznych.

Wiedza dziedzinowa to opis obiektów, zdarzeń, stwierdzeń należących do dziedziny, w której system ma działać. W przypadku tworzenia systemu paszportyzacji dla ZEB elementami wiedzy dziedzinowej są takie pojęcia jak „napięcie elektryczne”, „słup”, „transformator”, „przesył energii” czy „naprawa urządzenia”.

Metodologia tworzenia systemów opisuje sposób przetwarzania zestawu wiedzy początkowej („wymagań”) w działający, wdrożony system. Metodologia składa się z zestawu technik, na przykład dotyczących sposobu kierowania projektem, sposobu wykonywania analizy, sposobu projektowania systemu, sposobu zbierania danych w terenie (w przypadku ZEB) czy sposobu opracowywania procedur działania systemu. Pojęciami występującymi w dziedzinie metodologii są na przykład: „harmonogram”, „zasób”, „klasa”, „obiekt”, „system”, „moduł”, „procedura”, „baza danych”, „tabela”, „scenariusz testowy”.

Umiejętność tworzenia tekstów technicznych pozwala zebrać uzyskaną wiedzę dziedzinową i wypracowaną metodę tworzenia systemu i zaprezentować ją w sposób spójny i zrozumiały dla czytelnika. Podstawowym pojęciem z obszaru tworzenia opracowań technicznych jest „zapis”, czyli dowolny fakt z obszaru wiedzy dziedzinowej lub metodologii tworzenia systemów, który jest zapisywany w tworzonym tekście. Innymi pojęciami z tego obszaru mogą być „model pojęć”, „oznaczenie zapisu”, „składowa zapisu”.

Żeby tekst techniczny był zrozumiały dla czytelnika, musi on spełniać kilka warunków. Po pierwsze musi on być uporządkowany i wewnętrznie niesprzeczny. Niniejsze opracowanie poświęcone jest wybranym metodom wspomagającym tworzenie uporządkowanych i wewnętrznie niesprzecznych opracowań techniczno-zarządczych.

Metody te to:

  • Znakowanie pojęć
  • Mikrostandardy
  • Utworzenie modelu rodzajów pojęć (zaawansowane)

Zastosowanie tych trzech metod nie gwarantuje wytworzenia czytelnego opracowania technicznego. Muszą one być uzupełnione przede wszystkim o umiejętność prostego,  zrozumiałego i jednoznacznego formułowania myśli przez autorów. Jednak sprawne stosowanie zalecanych metod zawsze znacznie poprawia jakość wytworzonego produktu.

Model typów pojęć występujących w tekście technicznym, sposób znakowania zapisów oraz stosowane mikrostandardy powinny być przygotowane przez głównego autora opracowania i powinny być podstawą do opracowania szablonu opracowania.

Zakres dokumentu

Zadaniem dokumentu techniczno–zarządczego jest zakomunikowanie podjętych decyzji oraz przekazanie uzasadnienia tych decyzji. Zadaniem takiego dokumentu nie jest krzewienie wiedzy dziedzinowej czy wiedzy z zakresu metodologii tworzenia systemu. Jeśli autor uważa, że wiedza taka jest potrzebna, to powinien rozważyć umieszczenie odpowiedniego załącznika. Prezentowanie wiedzy w dokumencie techniczno-zarządczym zwykle zaburza tok lektury i utrudnia zrozumienie jego właściwej treści, czyli podjętych decyzji.

Znakowanie pojęć

Opracowanie techniczne powinno mieć swój system znakowania pojęć. Celem tworzenia systemu znakowania jest umożliwienie łatwego odwoływania się do istniejących zapisów.

Zwykle system znakowania zapisów opiera się na wprowadzeniu dwóch składowych:

  • numeru,
  • krótkiej nazwy.

Numer jest wykorzystywany do numerowania pojęć wewnątrz ich rodzajów. Numer składa się zwykle z krótkiego prefiksu i kolejnej liczby.

Krótka nazwa powinna składać się z nie więcej niż trzech słów i powinna bardzo zwięźle opisywać znaczenie pojęcia.

Tabela 1 pokazuje przykłady znakowania kilku pojęć związanych z ofertą na system paszportyzacji infrastruktury dla ZEB.

Tabela 1. Przykłady znakowania pojęć

Rodzaj pojęcia

Prefix

Przykłady

Numer

Krótka nazwa

Cel Biznesowy

CB

CB_001

Przewaga konkurencyjna

CB_002

Sprawna obsługa klienta

CB_003

Szybkie naprawy infrastruktury

Wymaganie

WM

WM_001

Pełna ewidencja infrastruktury

WM_002

Uzyskiwanie warstw map

Funkcja

FN

FN_001

Wyliczanie obciążeń

FN_002

Prezentacja graficzna

Moduł

MD

MD_001

Inwentaryzacja Danych

MD_002

Prezentacja Danych

MD_003

Obliczenia Eksploatacyjne

 

Sposób znakowania pojęć może uwzględniać strukturę systemu. Często spotykanymi uzupełnieniami systemu znakowania jest uwzględnienie podziału systemu na moduły lub uwzględnienie autora zapisów w jego numerze.

Na przykład moduły mogą mieć następujące skróty:

MD001           Inwentaryzacja Danych         ID

MD002           Prezentacja Danych               PD

MD003           Obliczenia Eksploatacyjne     OE

Przy takich oznaczeniach modułów funkcje mogą mieć nadawane numery w postaci FN_ID_001, FN_OE_001 i td.

Proponowany tu system znakowania pojęć jest niezbyt rygorystyczny. Istnieją systemy o wiele bardziej sformalizowane: na przykład w opisie modelu CMMI (http://www.sei.cmu.edu/cmmi/) osobny identyfikator ma każdy akapit tekstu.

Sposób znakowania pojęć powinien być opracowany przez osobę odpowiedzialną za wyprodukowanie opracowania i powinien być załącznikiem do szablonu opracowywanego dokumentu.

Mikrostandardy

Każdy rodzaj pojęcia ma zestaw informacji, który powinien być wykorzystywany do opisywania pojęć tego rodzaju. Jeśli chcemy, żeby wszystkie osoby uczestniczące w procesie tworzenia opracowania technicznego zbierały wszystkie wymagane informacje dotyczące danego rodzaju pojęć, to musimy ten zestaw informacji jednoznacznie zdefiniować.

Jeśli do tworzenia opracowania wykorzystujemy narzędzia typu CASE, to pełny zestaw informacji stosowalnych do opisu pojęcia, jest zwykle wbudowany w dane narzędzie. Na przykład w diagramerze VISIO do opisu pojęcia „class” mogą być stosowane pola Name, Stereotype, Documentation, Visibility, IsRoot, IsLeaf, IsAbstract, IsActive, Attributes, Operations, Receptions... i wiele innych. W tej sytuacji mamy dwa problemy. Po pierwsze należy określić, które z powyższych informacji są rzeczywiście potrzebne przy tworzeniu naszego opracowania. Możemy na przykład zawęzić opis klasy do wykazu atrybutów, wykazu funkcji oraz słownego opisu. Drugi problem to zestaw informacji, które muszą być zawarte w polach nie mających postaci doprecyzowanej przez autora narzędzia typu CASE. Najczęściej spotykanymi polami tego rodzaju są pola typu „opis” (w VISIO pole to nazywa się „Documentation”). Dla takiego pola należy określić mikrostandard, precyzujący jaką strukturę ma mieć to pole przy opisie każdego pojęcia. Na przykład możemy wymagać, żeby pole „Documentation” w specyfikacji pojęcia „klasa” zawsze zawierało następujące segmenty:

·         Pierwsze zdanie musi mieć postać: „<nazwa klasy> jest to....”. Na podstawie takiego zdania musi istnieć możliwość stwierdzenia, czy coś jest czy nie jest instancją (egzemplarzem, wcieleniem) klasy (obiektem należącym do klasy).

·         Następne zdania powinny opisywać inne zasadnicze własności klasy.

·         Sekcja DYNAMIKA KLASY powinna zawierać informacje o tym, w jakiej sytuacji biznesowej obiekt należący do klasy jest tworzony; kiedy jest modyfikowany i ewentualnie usuwany.

·         Sekcja ŹRÓDŁO INFORMACJI powinna zawierać odniesienie do dokumentu lub osoby, która przekazała informacje będące podstawą do wyspecyfikowania klasy.

Jeżeli przy tworzeniu dokumentu nie wykorzystujemy narzędzi typu CASE, to zadanie określenia mikrostandardu ulega rozszerzeniu. Należy wskazać (a nie wybrać z predefiniowanego zestawu) zestaw informacji opisujących dane pojęcie. Części opisu pojęć, które, w przypadku korzystania z narzędzi typu CASE, są umieszczane w ogólnych polach opisowych, mogą stać się samodzielnymi sekcjami opisu.

Podsumowaniem krótkiego opisu (meta)pojęcia „mikrostandard” może być stwierdzenie: musimy wiedzieć, jakie informacje o każdym pojęcie analityk (autor dokumentu) powinien zebrać i w jaki sposób powinien je zapisać.

Mikrostandardy opisów każdego pojęcia powinien być częścią szablonu przygotowywanego dokumentu.

Zaawansowane: model rodzajów pojęć

Rodzaj pojęcia jest to zbiór pojęć pełniących taką samą rolę w opracowaniu technicznym. Przykładami rodzajów pojęć mogą być:

  • Faza projektu
  • Element WBS
  • Założenie
  • Cel biznesowy
  • Cel systemowy
  • Wymaganie
  • Funkcja
  • Moduł
  • Klasa
  • Tabela danych
  • Etap projektu
  • Test modułu
  • ....

Pomiędzy rodzajami pojęć zachodzą relacje. Przykładami relacji zachodzących pomiędzy rodzajami pojęć są na przykład:

  • Cel biznesowy generuje wymaganie
  • Cel systemowy zapewnia osiągnięcie celu biznesowego
  • Założenie wpływa na moduł
  • Funkcja wynika z wymagania
  • Moduł realizuje funkcję
  • Moduł jest wytwarzany w etapie projektu
  • Tabela danych należy do modułu
  • Test modułu działa na moduł
  • Funkcja jest sprawdzana przez test modułu
  • ......

Elementem przygotowania do utworzenia opracowania technicznego powinno być wytworzenie modelu rodzaju pojęć.

Ponieważ modele rodzajów pojęć bywają zapisywane w postaci zbliżonej do modelu danych oraz modele te stosowano pierwotnie do opisywania struktur modelów danych, model te czasami nazywa się „metamodelami danych”, „metamodelami pojęć” albo krótko „metamodelami”.

Wskazane jest przedstawienie metamodelu na diagramie. Rysunek 1 prezentuje fragment przykładowego metamodelu wykonanego w narzędziu Visio 2000 jako model klas UML.

 

Rysunek 1.  Fragment przykładowego metamodelu

Diagram metamodelu może być wytworzony za pomocą dowolnego narzędzia służącego do graficznego modelowania danych; może to być narzędzie zarówno wykorzystujące techniki obiektowe jak i strukturalne.

Opis metamodelu, zawierający:

·         nazwy rodzajów pojęć występujących w opracowaniu,

·         nazwy związków zachodzących pomiędzy rodzajami pojęć,

·         diagram metamodelu (jeżeli jest utworzony)

powinien być załącznikiem do szablonu opracowywanego dokumentu.

Celem utworzenia metamodelu jest określenie podstawowej struktury tworzonego opracowania. Każdy zapis, każde pojęcie i każdy rodzaj pojęcia powinien mieć ściśle określone znaczenie w dokumencie. Jeśli nie wiemy, jaka może być relacja danego pojęcia z innymi pojęciami w dokumencie, to nie warto takiego pojęcia zapisywać.

W mniejszych dokumentach nie jest konieczne jawne tworzenie metamodelu. W PMI PMBoK często używane jest stwierdzenie typu „<An item> may be formal or informal, higly detailed or broadly framed based on the needs of the project.” Takie samo stwierdzenie może się odnosić do metamodelu. Ale metamodel – czyli opis pojęć i ich ról w dokumencie - musi istnieć zawsze, niezależnie od formy jego przekazywania. Ma on zasadnicze znaczenie porządkujące dla tworzonego dokumentu technicznego.

Podsumowanie

Metamodel opisuje główne pojęcia występujące w dokumencie oraz zachodzące pomiędzy nimi związki. Mikrostandardy mówią, w jaki sposób należy opisywać każdy rodzaj pojęcia występujący w opracowaniu. Te dwa elementy zapewniają, że tworzone opracowanie będzie zawierało wyłącznie informacje rzeczywiście potrzebne dla uzyskania celu, jaki jest stawiany przed dokumentem oraz, że będą zawierać tylko potrzebne informacje. Utworzenie spójnego metamodelu w szczególności powinno gwarantować możliwość śledzenia spójności pomiędzy informacjami wejściowymi, czy też początkowymi (np. wymagania na system) a celami stawianymi przed opracowaniem (np. wskazanie właściwości modułów implementujących system).

Wprowadzenie systemu znakowania pojęć ułatwia odwoływanie się do stwierdzeń zawartych w dokumencie. W szczególności stwierdzeniami takimi są opisy związków pomiędzy występującymi pojęciami. Na przykład przy definiowaniu testów, wykorzystanie systemu oznaczeń znacznie ułatwia wskazywanie wymagań, które są weryfikowane przez konkretne testy.

Stosowanie opisanych tu metod tworzenia opracowań technicznych jest znacznie ułatwione, jeśli do ich tworzenia wykorzystywane są narzędzia typu CASE, gdyż, jak wspomniano wyżej, podstawą projektowania narzędzi CASE są właśnie modele pojęć stosowanych w procesie tworzenia systemów.

Podjęcie decyzji realizujących przedstawione metody tworzenia tekstów technicznych należy zawsze do głównego autora opracowania. Jego obowiązkiem jest przekazanie odpowiednich zaleceń pozostałym współautorom i zapewnienie, że zalecenia te są właściwie zrozumiane przez pozostałych autorów.

Co zrobić z ustawą Prawo Zamówień Publicznych?

Co zrobić z Urzędem Zamówień Publicznych?

Kto ma wygrywać publiczne przetargi?

Czy najniższa cena oferty gwarantuje najniższy koszt?

Program rozwoju sportu

Wiedza o projektach

Model zarządzania wiedzą o projektach

Wiedza o projektach

Zarządzanie projektami nastawione na wiedzę

Agregaty projektów

Rodziny projektów

Agregaty projektów

Jednolity model zarządzania portfelami

Podstawy zarządzania portfelami

Modele dojrzałości

Dojrzałość systemów zarządzania projektami  

Dojrzałość metodyk zarządzania projektami

Meta-dojrzałość zarządzania projektami

Standardy i metodyki

Analiza ISO 21500 i porównanie z PMBoK® Guide

Siedem głównych standardów zarządzania projektami

Ogólne porównanie PMBoK, Prince 2 i CMMI

Szczegółowe porównanie PMBoK, Prince 2 i CMMI

Standardy PMI – spojrzenie krytyczne

Narzędzia Primavera a PMBoK

Zarządzanie jakością

Jakość w projektach informatycznych

Jakość dokumentów

Analiza

Analiza strategiczna

Analiza

Tworzenie tekstów analitycznych