rozdział 12

Rozdział 12 Testowanie dokumentacji
W TYM RODZIALE Rodzaje dokumentacji oprogramowania Znaczenie testowania dokumentacji Pod jakim kątem testować dokumentację Rzeczywistość testowania dokumentacji
W rozdziale 2-im „Proces wytwarzania oprogramowania” zostało powiedziane, że w skład produktu informatycznego wchodzi – oprócz oprogramowania – wielel innych składników. Ich znaczna część – to dukumentacja.
W dawnych dobrych czasach, dokumentacja składała się co najwyżej z pliku „czytaj.to” na dyskietce razem z oprogramowaniem, albo z jednostronicowej instrukcji włożonej do pudełka z programem. Dzisiaj jest tego znacznie, znacznie więcej – często dokumentacja wymaga więcej pracy i wysiłku niż samo oprogramowanie.
Tester oprogramowania nie musi – wbrew nazwie – ograniczać się do testowania tylko oprogramowania. Odpowiedzialność testera powinna dotyczyć wszystkiego, co wchodzi w skład produktu informatycznego, a więc również kontroli poprawności dokumentacji.
W tym rozdziale zapoznamy się z metodami testowania dokumentacji i z tym, jak włączyć je w całość procesu testowania. Najważniejsze punkty rozdziału to: 104.Różne rodzaje dokumentacji 105.Znaczenie testowania dokumentacji 106.Pod jakim kątem testować dokumentację Rodzaje dokumentacji oprogramowania
Gdyby dokumentacja oprogramowania składała się tylko i wyłącznie z pliku „czytaj.to”, nie byłoby wielkich kłopotów z testowaniem. Wystarczyłoby sprawdzić, czy plik zawiera wszystkie potrzebne dane, czy dane są poprawne technicznie i – na dodatek – możnaby wykonać kontrolę pisowni i przeciwwirusową dyskietki. Ale czasy dokumentcji składającej się tylko z pliku „czytaj.to” dawno minęły.
Dzisiaj dokumentacja oprogramowania stanowi zwykle znaczną część produktu. Czasem można wręcz mieć wrażenie, że produkt to sama dokumentacja z dodaną odrobiną oprogramowania.
Oto lista pozycji które należy zaliczyć do dokumentacji. Nie każdy rodzaj oprogramowania będzie miał wszystkie pozycje z listy, ale i takie mogą się trafić. 107.Tekst i grafika na opakowaniu. Wchodzi w to pudełko, etykiety, obwoluta, plastikowe koperty i tak dalej. Ta dokumentacja często zawiera fragmenty interfejsu oprogramowania, listy funkcji, wymagania systemowe, dane na temat praw autorskich. 108.Materiały reklamowe i marketingowe. To są te papierki które każdy zwykle szybko wyrzuca, ale są to mimo wszystko istotne narzędzia wpierające sprzedaż dodatkowego oprogramowania, umów serwisowych itd. Ta informacja musi być poprawna, aby klienci traktowali ją poważnie. 109.Gwarancja/rejestracja. Ma to zwykle formę formularza, który klient wypełnia i wysyla do producenta aby zarejestrować oprogramowanie. Bywa również częścią oprogramowania, którą klient wypełnia wprost przy komputerze albo nawet potwierdza interakcyjnie. 110.EULA. Wymawia się to „jula” i oznacza End User License Agreement (Umowa Licencyjna dla Użytkowanika Końcowego). Jest to dokument o mocy prawnej, w którym klient zobowiązuje się – między innymi – nie kopiować oprogramowania ani nie pociągnać producenta do odpowiedzialności karnej za szkody spowodowane przez ewentualne awarie oprogramowania. EULA drukuje się niekiedy na kopercie zwierającej nośnik programu – dyskietkę albo CD. Może też pojawić się na ekranie w trakcie procesu instalacji. Przykład EULA znajduje się na rysunku 12.1.
Rysunek 12.1 „EULA” jest częścią dokumentacji oprogramowania i wyjaśnia prawne warunki posługiwania się programem.
111.Etykiety i nalepki. Mogą znajdować się na nośniku informacji (dyskietka, CD), na pudełku, na drukach. Mogą to być też nalepki z numerem seryjnym, albo nalepki których rozdarcie oznacza przyjęcie warunków licencji. Na rysunku 12.2 znajduje się przykład etykiety na dyskietkę i informacja, którą musi się skontrolować. 112.Instrukcje instalacji i ustawień programu. Czasem ta informacja znajduje się na nośniku programu, ale bywa też dołączona jako osobny arkusz, lub – dla skompliwanego oprogramowania – jako cały podręcznik. 113.Podręcznik użytkownika. Użyteczność i elastyczność interakcyjnych podręczników spowodowała, że podręczniki drukowane spotyka się dziś o wiele rzadziej niż niegdyś. Większość programów zawiera obecnie niewielki drukowany podręcznik zawierający podstawowe wiadomości, a wszelkie informacje szczegółowe znajdują się w podręczniku interakcyjnym. Podręczniki interakcyjne rozprowadza się albo razem z oprogramowaniem na tym samym nośniku informacji, albo przez Internet, albo za pomocą obu metod. 114.Pomoc interakcyjna. Pomoc interakcyjna często stanowi jedność z podręcznikiem interakcyjnym, a czasem wręcz go zastępuje. Pomoc intercyjna ma zwykle indeks i daje się przeszukiwać, co wybitnie ułatwia znajdowanie potrzebnej infomacji. Wiele systemów pomocy interakcyjnej pozwala nawet dokonywać poszukiwań przy pomocy pytań fomułowanych w języku naturalnym. Użytkownik może na przykład napisać „Pokaż mi jak skopiować tekst z jedneg programu do drugiego” i otrzymać właściwą odpowiedź.

Nazwa programu
Języki Dane na temat dyskietki
Rodzaje platform dla oprogramowania
Numer identyfikacyjny programu
Instrukcje dla instalacji
Prawa autorskie
Wersja programu
Instrukcje instalacyjne znajdują się w Dokumentacji „Jak zacząć”
Rysunek 12.2 Na etykiecie dyskietki znajduje się dużo informacji, która musi zostać skontrolowana przez testera. 115.Seminaria, programy asystujące, kursy interakcyjne. W tych narzędzich często znajduje się zarówno kod programu jak i pisemna dokumentacja. Często stanowią mieszankę treści tekstowych oraz oprogramowania, zintegrowaną z systemem pomocy interakcyjnej. Użytkownik może zadać pytanie, a program prowadzi go przez wsztkie kroki potrzebne do wykonania zadania. Pomocnik Microsoftu, zwany czasem jako „facet-spinacz” (rysunek 12.3) jest przykładem takiego systemu. 116.Próbki, przykłady, wzory. Przykładem może być program do przetwarzania tekstu, zawierający formularze albo próbki dokumentów, które użytkowanik może wypełnić i szybko uzyskać w ten sposób dokumentcję o profesjonalnym układzie. Kompilatory mogą zawierać fragmenty kodu ilustrujące, jak posługiwać się danym aspektem języka. 117.Komunikaty o błędach. Kilkakrotnie były już w tej książce omawiane jako przykład tematu często zaniedbywanego. Zaliczyć można je również do dokumentacji.

Rysunek 12.3 Pomocnik Micorsoftu jest przykładem bardzo rozbudowanego systemu pomocy i nauczania. Znaczenie testowania dokumentacji
Dla użytkowników wszystkie elementy produktu nie będące oprogramowaniem są po prostu częścią produktu informatycznego. Dla użytkownika jest nieistotne czy dany element został skonstruowany przez programistę, autora tekstów czy też przez grafika. Dla użytkownika istotna jest jakość całego produktu.
Jeśli użytkownik zostanie wprowadzony w błąd przez mylne instrukcje instalacyjne albo przez nieprawidłowe komunikaty o błędach, będzie to dla niego równoznaczne z błędami oprogramowania – które powinny zostać znalezione przez testerów.
Dobra dokumentacja na trzy sposoby wpływa na ogólną jakość produktu: 118.Poprawia użyteczność. Pamiętamy jeszcze z rozdziału 11-ego „Testowanie użyteczności” wszystkie zagadnienia dotyczące użyteczności produktu? Użyteczność zależy w znacznym stopniu od jakości dokumentacji. 119.Podnosi niezawodność. Niezawodność zależy od tego, jak stabilne i spójne jest oprogramowanie. Czy program wykonuje to, czego oczekuje użytkownik, w dodatku we właściwym czasię? Jeśli użytkownik zapoznał się z dokumentcją, posłużył programem i uzyskał nieoczekowane wyniki, mamy do czynienia z niską niezawodnoiścią. Jak dowiemy się w dalszej części tego rozdziału, testowanie oprogramowania przez dokumentacje i dokumentacji przez oprogramowanie jest dobrym sposobem, by znaleźć błędy w jednym i w drugim.
120.Obniża koszty serwisu. Dowiedzieliśmy się w rozdziale 2-im, że błędy znalezione przez użytkownika mogą kosztować 10 do 100 razy więcej w porównaniu z błędami znalezionymi i skorygowanymi wcześniej w procesie wytwarzania produktu. Jedną z przyczyn jest to, że klienci nie mogący spobie poradzić z programem zwracają się do dostwacy o pomoc, której udzielenie jest kosztowne. Dobra dokumentacja może w znacznym stopniu przyczynić się do ograniczenia tych kosztów ułatwiając pracę użytkowników.
Dla testera oprogramowania dokumentacja zasługuje na tę samą uwagę i wysiłek co kod programu. Stanowią one jedną całość dla użytkownika. Pod jakim kątem testować dokumentację
Testowanie dokumentcji odbywa się na dwóch poziomach. Jeśli ona nie jest kodem, jak na przykład drukowany podręcznik użytkownika lub tekst na opakowaniu, testowanie jest statycznym procesem, jak opisany w rozdziałach 4-ym i 6-ym. Można je wówczas traktować jak rodzaj redakcji technicznej lub korekty. Kiedy dokumentacja i kod są ze soba ściśle połączone, jak na przykład w wypadku interakcyjnego podręcznika posługującego się hiperpołączeniami albo w wypadku pomocnego asystentaspinacza, testowanie staje się dynamiczne i stosujemy w nim techniki, które poznaliśmy w rozdziałach 5-ym i 7-ym. Mamy wtedy do czynienia z testowaniem oprogramowania.
Dokumentację najlepiej testować tak samo, jak będzie się nią posługiwał użytkowanik, niezależnie od tego, na ile jest statycznym tekstem, a na ile kodem. Należy ją starannie przeczytać, wykonać każdy z opisanych kroków, sprawdzić każdy rysunek i wypróbować każdy opisany przykład. W ten sposób znajdzie się błędy zarówno w programie, jak i w dokumentacji.
Tabela 12.1 zawiera prostą listę kontrolną do zastosowania przy konstruowaniu zadań testowych do dokumentacji.
Tabela 12.1 Lista kontrolna do testowania dokumentacji

Co sprawdzić Co uwzględnić Zagadnienia ogólne Czytelnicy Czy dokumentacja zwraca się do właściwych czytelników, nie do zbyt początkujących, nie do zbyt zaawansowanych? Terminologia Czy terminologia jest stosowna dla czytelników? Czy nazwy używane są konsekwentnie? Jeśli używa się skrótów, czy są one powszechnie zrozumiałe lub zdefiniowane z tekście? Należy upewnić się, czy nie stosuje się omyłkowo wewnętrznej terminologii stosowanej w firmie. Czy dostępny jest poprawny indeks i referencje do terminologii? Treść i zawartość Czy dokumentcja nie zawiera zbędnych tematów? Czy żadnych zagadnień nie brakuje? Warto zwrócić uwagę na opisy funkcji, które być może zostały usunięte z produktu, o czym jednak nie poinformowano autora dokumentacji technicznej. Czy materiał jest opisany dostatecznie szczegółowo? Poprawność Same fakty Czy informacja jest poprawna technicznie? Warto szukać błędów wynikających z posługiwania się przez autorów przestarzałą specyfikacją lub naginania prawdy przez dział marketingu. Spawdza się także spis treści, indeks i referencje do numerów rozdziałów. Sprawdza się adresy hiperpołączeń. Czy prawidłowo podany jest numer telefonu do obsługi technicznej? Najprościej zadzwonić. Krok po kroku Cały tekst należy czytać powoli i starannie, postępować dokładnie według podanych instrukcji. Niczego nie przyjmuje się za oczywiste. Brakującego opisu nie mależy się próbować domyślać – klienci nie będą wiedzieć, czego brakuje. Uzyskane wyniki należy porównać z podanymi w dokumentacji. Rysunki i fragmenty ekranu Sprawdza się poprawność i dokładność rysunków. Czy ilustracja zawiera właściwą treść? Należy sprawdzić, czy fragmenty ekranu nie pochodzą z poprzedniej wersji produktu. Czy podpisy pod rysunkami są poprawne? Próbki  i przykłady Każdą próbkę należy załadować i użyć tak samo, jak zrobi to  użytkowanik. Jeśli to jest kod, należy go skopiować i wypróbować. Nic bardziej żałosnego niż nie działające próbki kodu – a mimo to spotykamy się z nimi bardzo często!

Pisownia i gramatyka
W doskonałym świecie tego typu błędy nigdy nie docieralyby do testerów. Programy do kontroli pisowni i gramatyki są powszechnie dostępne i należy je stosować. Mogło się jednak zdarzyć, że zapomniano skontrolować fragment tekstu lub że specjalistyczny, techniczny termin uniknął kontroli. Rysunki i ilustracje zawierające fragmenty ekranu były przypuszczalnie sprawdzane tylko ręcznie, więc obowiązje wobec nich zasada ograniczonego zaufania.
W końcu, jeśli mamy do czynienia z dokumntacją „napędzaną programem”, należy ją przetestować tak samo, jak całą resztę oprogramowania. Sprawdza się, czy indeks jest kompletny, czy szukanie daje poprawne wyniki, czy hiperpołączenia i miejsca aktywne prowadzą pod właściwe adresy. Warto posłużyć się techniką podziału na klasy równoważności by zadecydować, co się kontroluje. Rzeczywistość testowania dokumentacji
Na koniec rozdziału trzeba zapoznać się z realiami, które powodują, że wytwarzanie i testowanie dokumentacji różni się jednak od wytwarzania oprogramowania. Rozdział 3-ci nosił tytuł „Testowanie oprogramowania w rzeczywistości”. Poniższe zagadnienia możnaby nazwać realiami testowania dokumentacji. 121.Dokumentacja często otrzymuje najmniej uwagi, środków i osób. Wydaje się istnieć specyficzna mentalność, że w produkcie informatycznym przede wszystkim liczy się oprogramowanie, cała reszta jest drugorzędna. W rzeczywistości klienci kupują cały produkt informatyczny i inne rzeczy są równie ważne jak bajty i bity. Ponosząc odpowiedzialność za testowanie jakiejś funkcji w oprogramowaniu, należy dopatrzyć, by w skład testowania wszedł również test dokumentacji. Należy poświęcić mu tyle samo uwagi co oprogramowaniu i jego błędom. 122.Zdarza się, że osoby piszące dokumentację nie są specjalistami w dziedzinie oprogramowania lub jego zakresu programu. Tak samo jak tester nie musi być ekspertem od rachunkowości by móc testować arkusz kalkulacyjny, tak samo autor dokumentacji nie musi znać doskonale funkcji programu by móc pisać dokumentację. Nie można więc zakładać, że autor zdoła wyobyć prawdę ze źle napisanych specyfikacji i ze skomplikowanych, niejasno udokumentowanych funkcji produktu. Warto blisko współpracować z autorami dokumentacji, by upewnić się, że mają dostęp do potrzebnej informacji i że znaja konstrukcje produktu1. Testerzy mogą też poinformowc autorów dokumentacji, jakie funkcje programu są szczególnie trudne do zrozumienia lub do zastosowania, tak by mogli lepiej wyjaśnić je w dokumentacji.
1 W takim razie testerzy powini mieć pensje prezesów zarządów spółek, skoro maja kompensować niedbalstwo i niekompetencję wszystkich innych osób w firmie i w projekcie… (przyp. tłumacza).
123.Produkcja dokumetacji drukowanej zajmuje tygodnie albo nawet miesiące, podczas gdy oprogramowanie można opublikować niemal natychmiast na Internecie albo na CD. Z powodu tej różnicy, dokumentację często trzeba sfinalizować i zamrozić zanim oprogramowanie zostanie wykończone. Jeśli program zmieni się, albo odkryte zostaną błędy w tym krytycznym dla dokumentacji okresie, nie da się już unacześnić dokumentacji. Dlatego wymyśłono pliki „czytaj.to”. Za ich pomocą można poinformować klientów o zmianach wprowadzonych w ostatniej chwili. Jedyną radą jest mieć i stosować dobry model wytwarzania oprogramowania, powstrzymywać wypuszczenie papierowej dokumentacji jak tylko długo można i publikować jak największą część dokumentacji razem z progamem, na nośniku programu lub na Internecie.
Podsumowanie
Miejmy nadzieję, że ten rozdział zdołał przekonać czytelników, że produkt informatyczny składa się nie tylko z pisanego przez programistów kodu. Dokumentcja oprogramowania – we wszystkich postaciach – sporządzana przez autorów, ilustratorów, autorów indeksacji i tak dalej, może być bardziej pracochłonna przy wytwarzaniau i testowaniu niż samo oprogramowanie.
Z punktu widzenia użytkowanika wszystkio to są składniki tego samego produktu. Błąd w pomocy interakcyjnej, która nie jest w stanie wyjaśnić znacznenia jakiegoś podstawowego określenia, nieprawidłowa instrukcja instalacji czy błąd literowy to takie same błędy jak każdy inny błąd w oprogramowaniu. Testując porządnie dokumentację, znajduje się błędy zanim znajdą je użytkownicy.
W następnym rozdziale zapoznamy się z testowaniem czegoś, co niemal w całości jest samą dokumentacją – tekst, grafika i hiperpołączenia wraz z ukrytą pod nimi platformą. Techniki, które poznaliśmy dotąd, da się znakomicie zastosować do testowania witryn WWW. Pytania
Pytania mają na celu ułatwienie zrozumienia. W aneksie A „Odpowiedzi na pytania” znajdują się prawidłowe rozwiązania – ale nie należy ściągać!
1.Uruchom program Paint w Windows (zobacz rysunek 12.4) i poszukaj przykładów dokumnetacji którą należałoby przetestować. Co można znaleźć?
Rysunek 12.4 Jakie przykłady dokumentacji można znaleźć w programie Paint w Windows? 2. Indeks pomocy w programie Paint w Windows zawiera ponad 200 haseł począwszy od dodać własne kolory1, skończywszy na zmiana wielkości obrazu. Czy należy sprawdzić, czy każde z haseł indeksu porwadzi do właściwego rozdziału? Jak należałoby postąpić w przypadku 10000 haseł w indeksie? 3. Prawda czy fałsz: testowanie komunikatów o błędach jest częścią testowania dokumentacji. 4. Jakie są trzy podstawowe powody, dla których których test dokumentacji przyczynia się do poprawy ogólnej jakości produktu informatycznego?