|
Wprowadzenie
Logika dokumentu
Budowa dokumentu
Redakcja dokumentu
Odwołania
Wybrane właściwości MS Word
Właściwości językowe
W literaturze związanej z zarządzaniem jakością można
znaleźć wiele materiałów dotyczących cech jakościowych produktów mających tzw.
„bezpośrednią funkcjonalność”: programy komputerowe, budowle, farmaceutyki,
pojazdy. Nie wchodząc zbyt głęboko w szczegóły, wiele napisano o tym, że
programy komputerowe nie mogą mieć błędów i muszą być przyjazne dla
użytkownika. Budowle muszą mieć swoją wytrzymałość i muszą być bezpieczne.
Pojazdy muszą być sprawne, efektywne i bezpieczne. Dla zdefiniowanych cech
jakościowych literatura pełna jest opisu procedur ich weryfikacji.
Szczególnym rodzajem wytworu, który nie ma
bezpośredniej, „fizycznej” funkcjonalności, ale za to jest obecny zapewne
we wszystkich obszarach działania projektowego, jest dokument. Popularności
tego rodzaju produktów nie towarzyszy obfitość literatury opisującej ich
jakość. Wynika to zapewne z kilku niesłusznych przeświadczeń. Na przykład:
- Jakość
dokumentów nie jest równoznaczna z jakością wytwarzanego produktu.
- Ważne
są wyłącznie „twarde” zapisy znajdujące się w dokumencie, jego własna,
specyficzna dla dokumentu jakość ma znaczenie drugorzędne.
- „Pisać
każdy może”. Jeżeli ktoś skończył szkołę średnią (albo ma wyższy
poziom wykształcenia), to na pewno umie pisać.
W tym dokumencie, głównie na podstawie wieloletniej
własnej praktyki w obszarze kontroli jakości, opisałem zestaw cech, które
muszą mieć dobrze napisane dokumenty. Zestaw tych zaleceń jest zapewne
niepełny, co może stwarzać wrażenie niezgodności z jedną z opisywanych w
nim cech. Ale sprzeczność jest pozorna: niniejszy tekst jest dokumentem o
charakterze popularyzatorskim, a nie formalnym dokumentem projektowym.
Tekst dotyczy przede wszystkim dokumentów typu
analitycznego oraz procedur, ale większość zasad może być stosowanych do
dokumentów innego rodzaju, na przykład do dokumentacji użytkownika.
Tekst może być wykorzystany do tworzenia wzorców
dokumentów w projektach. Może także być podstawą do utworzenia listy
kontrolnej przy sprawdzaniu formalnej jakości dokumentów.
Tekst napisano z myślą o dokumentach tworzonych w
aplikacji MS Word. Z tego założenia wynika obecność sekcji poświęconej
niektórym zasadom redagowania tekstów w tym narzędziu.
Precyzyjna
definicja zasadniczych pojęć
Każdy dokument musi mieć w
początkowej jego części sekcję, w której powinny być zdefiniowane:
·
Wszystkie używane skróty,
·
Wszystkie pojęcia z obszaru, którego dotyczy
dokument, niezależnie od ewentualnego przeświadczenia autora o oczywistości
ich znaczenia,
·
Inne istotne pojęcia, jeśli ich zrozumienie
jest kluczowe dla zrozumienia dokumentu, lub pojęcie to nie jest stosowane
w sposób ogólnie przyjęty.
Jeśli w ramach projektu
powstaje wiele dokumentów (zwykle tak jest), to zalecane jest utworzenie
jednolitego słownika skrótów i pojęć dla całego projektu.
Niesprzeczność
zapisów
Pomiędzy zapisami dokumentu
nie może być sprzeczności. Tzn. jeśli w jednym
miejscu dokumentu istnieje zapis A, to z pozostałej części dokumentu nie
może, bezpośrednio ani pośrednio, wynikać zapis sprzeczny z zapisem A.
Konsekwentne
używanie zdefiniowanych pojęć
Wykluczone jest używanie
synonimów zdefiniowanych pojęć, o ile nie zostały one zdefiniowane w
początkowej sekcji dokumentu. Zdefiniowanych pojęć nie wolno używać w
znaczeniu innym, niż określone w słowniku.
Zalecane jest nietworzenie
synonimów; ich używanie utrudnia zrozumienie dokumentu.
Jednoznaczność
zapisów
W dokumencie nie należy
umieszczać zapisów pozwalających na ich dowolną interpretację (np.
opcjonalność bez określenia warunku zezwalającego na niewykonanie
czynności, używanie zapisów typu „w miarę możliwości”).
Precyzja
definicji zakres dokumentu
Na początku dokumentu zawsze
należy określić, jakich obiektów dotyczy dokument. Jeśli występują
wykluczenia z zakresu dokumentu, to należy je jednoznacznie opisać.
Kompletność
dokumentu
Dokument musi opisywać pełen
zestaw obiektów wynikający z jego definicji. Na przykład jeżeli dokument opisuje
ryzyka projektu, to najpierw należy ustalić na jakie kategorie ryzyk
projekt jest narażony, a później opisać każdą z tych kategorii. Jeżeli dokument
opisuje dokumentację projektu, to należy ustalić zestaw kategorii
dokumentacji, a potem opisać każdą z kategorii.
Jednolitość
sposobu tworzenia dokumentów
Dokumenty powinny być
tworzone w sposób jednolity. Jeżeli w ramach projektu tworzony jest więcej
niż jeden dokument określonego typu, to każdy z nich musi mieć taką samą
strukturę. Przykładami typów dokumentów mogą być specyfikacje modułów w
systemie informatycznym, procedury w systemie jakości.
Wykorzystanie
szablonów dokumentów zgodne z ich przeznaczeniem
Zwykle, jeśli w projekcie
powstaje wiele dokumentów tego samego typu, to najpierw przygotowywany jest
szablon dla każdego typu dokumentu. Szablon taki jest przygotowywany przez
osobę odpowiedzialną za formalną jakość dokumentów projektu. Z treści
szablonu powinno wynikać, jakie zapisy powinny znaleźć się w jego sekcjach.
Obowiązkiem osób tworzących
dokument na podstawie szablonu jest precyzyjne wypełnianie jego sekcji
zgodnie z ich przeznaczeniem.
Mikrostandardy
Jednolitość zapisów
dokumentów musi odnosić się do poziomu opisu bardziej szczegółowego niż
spis treści. Każda elementarna sekcja dokumentu musi mieć taką samą
strukturę.
Przykład: Definiowanie pojęć.
Żeby osiągnąć jednolitość
dokumentu nie wystarczy wymaganie umieszczenia ciągu definicji pojęć.
Należy ustalić, że każda definicja składa się z:
·
Zdania definiującego pojęcie, mającego
strukturę:
<obiekt definiowany>
jest to <jednoznaczna definicja obiektu>.
·
Opis zasadniczych cech obiektu
definiowanego.
·
Możliwe wyjątki.
Zgodność
tytułów z zawartością odpowiednich fragmentów
Zawartość każdego
tytułowanego fragmentu dokumentu (podrozdział, zadanie, rysunek…) musi być
zgodna z tytułem.
Grupowanie
adekwatnych informacji
Zbliżone pojęciowo informacje
powinny być opisane blisko siebie.
Jawne
zaznaczanie pustych sekcji
Jeśli sekcja dokumentu ma
pozostać pusta, to należy umieścić zapis informujący o tym. Nie należy
pozostawiać pól niewypełnionych.
Odwołania do
dokumentów zewnętrznych
Dla każdego dokumentu
zewnętrznego musi być referencja umożliwiająca jego identyfikację i
odnalezienie.
Precyzyjne
odwołania do dokumentów zewnętrznych
Jeżeli przy odwołaniach do
dokumentów zewnętrznych istotna jest tylko część zawartości takiego
dokumentu, to w referencji należy wskazać nie tylko dokument, ale i jego
właściwą część (rozdział, punkt, sekcję...).
Nieużywanie oznaczeń
wersji w referencjach do dokumentów podlegających zarządzaniu konfiguracją
Nie należy używać oznaczeń
wersji w referencjach do dokumentów podlegających zarządzaniu konfiguracją.
Używanie takich oznaczeń powoduje konieczność weryfikacji i modyfikacji
zbioru dokumentów w których takie odwołania mogą
wystąpić, po każdej zmianie wersji dowolnego dokumentu.
Niedefiniowanie
stylów przez autorów dokumentów
Autorzy dokumentów nie mogą
wprowadzać własnych stylów redakcyjnych. Cały dokument musi być napisany z
wykorzystaniem dokładnie tych stylów, które zostały zdefiniowane przez
autora szablonu.
Powtarzanie
nagłówków tabel
Tabele, które są umieszczane
na więcej niż jednej stronie muszą mieć na każdej stronie powtórzone
nagłówki.
Używanie
referencji kontrolowanych przez MS Word
Do podawania referencji do
zapisów znajdujących się w tym samym dokumencie należy używać mechanizmów
wbudowanych w MS Word (Wstaw / Odwołanie). Nie wolno ręcznie wpisywać
numerów rozdziałów, rysunków czy tabel.
Rozmiar pól
adekwatny do przewidywanej treści
Pola tworzonych formularzy
muszą mieć rozmiar umożliwiający wpisanie do nich przewidywanych treści.
Porządkowanie
zapisów w wyliczeniach i tabelach
Zapisy w wyliczeniach i
tabelach powinny być porządkowane zgodnie z logiką właściwą dla danego
zbioru (np. chronologia występowania zdarzeń). Jeśli nie jest możliwe
określenie takiego porządku, to zapisy powinny być porządkowane
alfabetycznie.
Jednolitość
przyjętych konwencji
Dla wszystkich dokumentów
należy stosować takie same konwencje redakcyjne.
Przykład.
Należy zawsze stosować takie
same znaki poprzedzające wyliczenie.
Poprawność
językowa
W dokumencie nie może być
błędów gramatycznych, interpunkcyjnych, składniowych i stylistycznych.
Definiowanie
pojęć w liczbie pojedynczej
W słowniku pojęć, o ile nie
są definiowane pojęcia z założenia występujące w liczbie mnogiej,
definiowane pojęcie należy zawsze podawać w liczbie pojedynczej.
Jednolita forma
gramatyczna zdań
Dokument powinien być pisany
w jednolitej formie gramatycznej. Na przykład dla procedur możliwe jest
przyjęcie trzeciej osoby liczby pojedynczej czasu teraźniejszego.
Długość zdań
nie większa niż 20 słów
Zasada odnosi się do
możliwości percepcji tekstu przez człowieka. Żadne zdanie nie powinno mieć
więcej niż ok. 20 słów. Jeśli zdanie jest dłuższe, człowiek ma trudności z
przyswojeniem zawartych w nim treści. Jeśli przy pierwszej redakcji okazuje
się, że długość zdania jest większa, to należy rozważyć jego podział na dwa
lub większą liczbę niezależnych zdań. Należy pamiętać, że wytwarzanie
tekstów jest, dla aparatu pojęciowego człowieka, znacznie łatwiejsze niż
jego przyswajanie (czytanie).
Wyliczenia: 7
plus minus 2 pozycje
Zasada także odnosi się do
możliwości percepcji. Wynika z jednego z podstawowych praw z zakresu
psychologii poznawczej. Człowiek nie jest w stanie przetworzyć jednocześnie
więcej niż właśnie ok. siedmiu jednostek informacji. Jeśli rozmiar
wyliczenia jest większy, to należy rozważyć wprowadzenie wyliczenia dwu-
lub więcej poziomowego.
|