14

Rozdział 17.
Tworzenie dokumentacji i plików pomocy

Drew Avis

Dziesięć przykazań autora dokumentacji

Rodzaje dokumentacji

Metodologia tworzenia dokumentacji elektronicznej

Formaty plików pomocy

WinHelp – sprawdzony standard

Microsoft HTML Help

Obsługa pomocy w bibliotece VCL

Materiały i narzędzia dla twórców dokumentacji

Chyba każdy użytkownik komputera „zaliczył” już przeglądanie plików pomocy i dokumentacji programu – czy to w poszukiwaniu opisu jakiejś czynności, czy też może informacji o błędzie. Ile razy zdarzało się nam, że odchodziliśmy z kwitkiem albo, co gorsza, uzyskane wiadomości okazywały się niepełne lub nieprawdziwe? Dokumentacja jest jednym z głównych źródeł

„jedyny” (oryginał) to spora przesada – moje konsultacje z dokumentacją Windows 9x można policzyć na palcach jednej ręki, a korzystam z tego systemu już 5 lat. Są jeszcze książki i nauka przez doświadczenie.

wiedzy użytkowników o programie i jako taka ma ogromny wpływ na sposób jego postrzegania. Jakość dokumentacji jest bardzo ważnym kryterium wyboru oprogramowania i w coraz większym stopniu uwzględniana jest w opiniach i recenzjach.

Problem jakości dokumentacji ilustruje prawdziwa historia, jaka zdarzyła się podczas tworzenia edytora Microsoft Word 97. Członkowie zespołu projektowego zdecydowali się przeprowadzić wywiad z użytkownikami poprzedniej wersji (Word 95) w celu ustalenia, jakie nowe możliwości i funkcje powinny znaleźć się w programie. Okazało się, że 80 procent życzeń użytkowników… zostało już spełnione. Wymienione przez nich funkcje były dostępne już w Wordzie 95, tyle że mało kto o nich wiedział! Jak widać, kiepskie rozwiązania interfejsu użytkownika i źle napisana dokumentacja potrafią skutecznie ukryć wiele możliwości programu.

Każda aplikacja, niezależnie od jej rozmiaru, wymaga dokumentacji – papierowej, elektronicznej lub obu rodzajów. W rozdziale tym przedstawimy metody tworzenia takiej dokumentacji, używane w tym procesie narzędzia i formaty danych oraz wskazówki dotyczące strategii dokumentowania programów.

Uwaga
Osoby zatrudnione w wielu większych firmach mogą prawdopodobnie pominąć cały ten rozdział, gdyż omówiona w nim tematyka po prostu ich nie dotyczy – tworzeniem dokumentacji zajmują się tam zwykle wyspecjalizowane zespoły. Programiści nie mający dostępu do takich luksusów – pracownicy małych firm, wolni strzelcy i niezależni konsultanci – powinni rozważyć skorzystanie z usług specjalistów (niestety, w warunkach krajowych możliwości w tym zakresie są znacznie mniejsze niż w USA – przyp. tłum.). Tych, którzy starają się robić wszystko we własnym zakresie, a zatem oprócz funkcji programisty, marketingowca, prezesa i księgowego muszą także pełnić rolę skryby, zapraszamy do lektury dalszej części rozdziału.

Dziesięć przykazań autora dokumentacji

Przed zagłębieniem się w techniczne rozważania na temat systemów pomocy i redagowania podręczników spróbujmy przedstawić kilka kluczowych elementów dobrej praktyki tworzenia dokumentacji technicznej. Oto one.

·         Znajomość odbiorcy. Wiedza na temat odbiorców programu (czyli użytkowników) oraz ich potrzeb i wymagań jest fundamentem, na którym opiera się cała strategia tworzenia dokumentacji.

·         ZKP – zwięzłość, kompletność, poprawność. Określenia te mówią same za siebie.

·         Konsekwencja formalna. Sposób przekazywania określonych informacji powinien być jednolity w obrębie całej dokumentacji – jeśli w jednym rozdziale używamy dla słów kluczowych pogrubienia, w innym nie możemy pisać ich kursywą. Warto tu rozejrzeć się nieco po materiałach dodatkowych, chociaż w języku polskim nie ma jak na razie na ten temat dobrej literatury. Własny podręcznik stylu publikuje m.in. wydawnictwo Microsoft Press.

·         Planowanie. Projektując harmonogram prac nad oprogramowaniem, należy uwzględnić czas przeznaczony na opracowanie dokumentacji.

·         Korekta. Napisanie dokumentacji to jeszcze nie wszystko – zawsze należy ją potem przeczytać i poprawić ewentualne błędy. Najlepiej odwołać się w tym przypadku do pomocy innej osoby (oczywiście znającej się na rzeczy i poprawnie posługującej się językiem).

·         Ilustracje. Co prawda obraz jest zwykle wart więcej niż tysiąc słów, jednak czasami potrafi on przysporzyć tysiąca zmartwień. Jeśli ilustracja wnosi coś nowego, czego nie da się wyrazić w tekście, należy jej użyć. Jeśli jest wyłącznie ozdobnikiem, należy się jej pozbyć. Jeśli do tego zajmuje pół megabajta – trzeba ją natychmiast usunąć.

·         Sprawdzenie w praktyce. Każdą procedurę opisaną w dokumentacji należy sprawdzić w praktyce. Pozwala to uniknąć przypadkowego pominięcia jakiegoś ważnego kroku, a także wyeliminować nadmiarowość opisu.

·         Informowanie użytkownika o wynikach operacji. Opisując jakąś czynność, nie wystarczy powiedzieć „Teraz kliknij OK” – wypada również poinformować użytkownika, jakie będą tego skutki.

·         Wczesne ostrzeganie. Należy zawsze informować użytkownika o niebezpieczeństwach związanych z daną operacją (możliwość utraty danych, destabilizacji systemu itd.). Informacje takie należy umieszczać przed opisem czynności, będących źródłem potencjalnego zagrożenia.

·         Ścisły związek dokumentacji z oprogramowaniem. Dokumentacja jest integralną częścią oprogramowania i w większości przypadków stanowi dla użytkownika podstawowe źródło informacji o programie.

Rodzaje dokumentacji

Jeszcze nie tak dawno pojęcie „dokumentacja” sprowadzało się na ogół do jednej książki zwanej ogólnikowo „podręcznikiem użytkownika”. Dzieło to nader często okazywało się być chaotycznym zbiorem opisów poleceń i wybranych komunikatów o błędach (zwykle nie tych, które akurat się trafiały). Postęp w technologii komputerowej przełożył się jednak również na techniki dokumentowania oprogramowania, a współczesne zestawy dokumentacji, o niebo dojrzalsze od niegdysiejszych „powielaczowych instrukcji”, zawierają liczne, zróżnicowane odmiany dokumentów. Zestawienie rodzajów dokumentacji (podzielonej ogólnie na papierową i elektroniczną) przedstawiamy poniżej (ponieważ wiele produktów dostępnych na rynku oprogramowania nie posiada polskich wersji, w nawiasach podajemy odpowiedniki angielskie – przyp. tłum.).

Elementy dokumentacji papierowej:

·         podręczniki użytkownika (User’s Manual);

·         podręczniki serwisowe (Troubleshooting Guide);

·         zestawienia funkcji i poleceń (Reference);

·         wprowadzenia (Quick Start);

·         listy klawiszy skrótu (Keyboard Shortcuts);

·         karty informacyjne i referencyjne (Quick Reference).

Elementy dokumentacji elektronicznej:

·         system pomocy (Help);

·         pomoc kontekstowa (Context-sensitive help);

·         kreatory (Wizard);

·         samouczki (Tutorial);

·         porady (wskazówki, „hasła na dziś”; Tip of the Day);

·         podpowiedzi (tzw. etykietki; ToolTip);

·         lokalne okienka pomocy (What’s This?);

·         pliki „Czytaj to” i „Co nowego” (Readme, Release notes);

·         strony WWW;

·         bazy wiedzy (Knowledge Base) i listy często zadawanych pytań (FAQ, Frequently Asked Questions).

Spore koszty druku i coraz większe możliwości elektronicznych systemów dokumentacji sprawiają, że producenci oprogramowania odchodzą od tradycyjnej, papierowej dokumentacji. Coraz więcej materiałów dostarcza się w formie plików i można oczekiwać, że przekaz elektroniczny w niedługim czasie całkowicie wyeliminuje tradycyjne, drukowane podręczniki. Firma Microsoft przyjęła taką strategię, wprowadzając na rynek system Windows 95, wyposażony w jeden tylko (do tego dość cienki) papierowy podręcznik instalacji. Niestety, elektroniczna dokumentacja Windows 95 jest daleka od doskonałości i nie jest chyba najlepszym wzorem do naśladowania.

Metodologia tworzenia dokumentacji elektronicznej

Przed rozpoczęciem prac nad dokumentowaniem aplikacji należy opracować plan realizacji tego zadania. Plan taki powinien precyzować rodzaje informacji przekazywanych użytkownikowi oraz sposób ich przekazywania. Punktem wyjścia jest tu często pytanie: „Kto będzie używał tego programu?”, czyli ustalenie kręgu odbiorców. Minimalny zestaw informacji ogólnych, przeznaczonych dla przeciętnego użytkownika, obejmuje opis głównych procedur (sposobów wykonywania podstawowych zadań), czemu poświęcimy nieco więcej uwagi w punkcie „Pomoc proceduralna” w dalszej części rozdziału. W następnym etapie należy określić rodzaj i zakres przekazywanych użytkownikowi informacji natury ogólnej (koncepcyjnej) i referencyjnej. Krok ten obejmuje ustalenie lokalizacji danych (w głównym pliku pomocy lub w pliku dodatkowym) oraz sposobu ich logicznego połączenia z opisami procedur. Na koniec do rozważenia pozostaje kwestia samouczka i przykładów, ułatwiających użytkownikowi samodzielną naukę obsługi programu.

Przedstawione wcześniej zasady dobrej praktyki tworzenia dokumentacji stosują się w równym stopniu do dokumentów elektronicznych, jednak specyfika tych ostatnich niesie ze sobą kilka czynników, które dodatkowo wpływają na ich organizację.

Kategorie systemów pomocy

Ze względu na zawartość i przeznaczenie systemy pomocy można podzielić na kilka kategorii, spełniających zapotrzebowanie na rozmaite rodzaje informacji (Hackos i Stevens). Jedna z możliwych klasyfikacji opiera się na podziale przekazywanych informacji na cztery kategorie:

·         proceduralne;

·         referencyjne;

·         koncepcyjne;

·         instruktażowe.

Pomoc proceduralna

W systemach pomocy przeznaczonych dla przeciętnych użytkowników dominują informacje natury proceduralnej (zobacz rysunek 17.1), opisujące metody wykonywania konkretnych zadań i zorientowane na uzyskanie określonych wyników. Prawidłowo skonstruowane opisy procedur wykorzystują na ogół wspólny punkt wyjścia (np. ekran główny lub menu główne aplikacji) i zawierają opisy poszczególnych kroków, których wykonanie prowadzi do zrealizowania zadania. Opis każdego kroku powinien zawierać informację o spodziewanym wyniku (np. „Na ekranie pojawi się okno otwarcia pliku”), zaś elementy wymagające uwagi lub ostrożności należy opatrzyć odpowiednimi uwagami.

Rysunek 17.1. Przykład opisu proceduralnego – system pomocy Microsoft Windows 98

Stworzenie dobrego opisu procedury nie jest zadaniem łatwym. Które kroki należy uwzględnić? Ile można założyć na temat wiedzy użytkownika – czy trzeba np. informować go, że do zamknięcia okna służy przycisk Zamknij? Na pytania te – a także na wiele innych – nie ma jednoznacznych i prostych odpowiedzi. Jednym z możliwych rozwiązań jest opisanie procedur w dwóch równoległych, odpowiednio zatytułowanych wersjach – jednej przeznaczonej dla początkujących użytkowników i drugiej – dla ekspertów. Można też zaoferować użytkownikowi tylko wersję „zaawansowaną”, a dodatkowe informacje dla nowicjuszy udostępniać w postaci oddzielnych okienek, dostępnych na żądanie (np. po kliknięciu myszą).

Dwa zasadnicze rodzaje informacji przekazywanych w ramach pomocy proceduralnej to opisy wykonywania zadań i funkcji oraz opisy usuwania usterek. O ile w pierwszym przypadku informacje przekazywane użytkownikowi można określić jako pomocne (ale nie bezwzględnie konieczne), dobrze skonstruowane procedury usuwania usterek okazują się nieocenioną pomocą we wszelkiego rodzaju kryzysach.

Poniżej podajemy kilka wskazówek, przydatnych w tworzeniu dokumentacji typu proceduralnego.

·         Na początku opisu procedury należy krótko przedstawić jej cel, np. „Celem tej operacji jest dodanie do bazy danych nowego użytkownika”.

·         Opis samej procedury należy osadzić we właściwym kontekście. Jeżeli dodanie danych do bazy wymaga uprzedniego utworzenia profilu użytkownika, należy o tym powiedzieć i zamieścić w opisie odnośnik do odpowiedniego tematu

·         Opisy poszczególnych kroków powinny zawierać informacje o spodziewanych wynikach. Jeżeli z wykonaniem danej czynności wiążą się jakieś zagrożenia (utrata danych, możliwość załamania aplikacji lub systemu), należy poinformować o tym na początku opisu, a nie (potencjalnie) post factum.

·         Ilość przekazywanej informacji należy ograniczyć do niezbędnego minimum.

Pomoc referencyjna

Kategoria ta obejmuje informacje nie przeznaczone do nauki i zapamiętania. Powinny one być umieszczone w oddzielnym dokumencie, zorganizowanym w sposób maksymalnie ułatwiający dostęp i przeglądanie (zobacz rysunek 17.2), co narzuca rygorystyczne wymagania w kwestii układu jego zawartości. Informacje typu referencyjnego mają na ogół naturę „abstrakcyjną” i „statyczną”, tj. nie są podawane na podstawie konkretnych zadań i procedur. Dobrze skonstruowany dokument referencyjny powinien być wyczerpujący i w miarę możliwości zawierać objaśnienia wszelkich tematów, jakie mogą pojawić się w danym kontekście. Na przykład słowniczek terminów używanych w programie powinien obejmować wszystkie nazwy i hasła, na jakie użytkownik może natrafić. Przykładami dokumentów referencyjnych mogą być zestawienia wykorzystanych w programie wzorów matematycznych i tabel danych, spisy literatury oraz opisy składni języków programowania.

Rysunek 17.2. Przykład opisu referencyjnego – plik pomocy serwera Local SQL Server ze spisem treści

Pomoc koncepcyjna

Opisy typu koncepcyjnego wyjaśniają mechanizmy działania programów i leżące u ich podstaw zasady (zobacz rysunek 17.3). Zawarte w nich informacje nie są na ogół niezbędne do realizacji konkretnych czynności ad hoc, okazują się natomiast przydatne w dłuższym horyzoncie czasowym. Zadaniem opisu koncepcyjnego jest udostępnienie użytkownikowi wskazówek i materiału pomocnego w wyborze sposobu działania, a także wskazanie opisów (ale nie bezpośrednie opisywanie) konkretnych czynności, które należy podjąć w celu osiągnięcia wybranego celu. Opis koncepcyjny nie musi być wyczerpujący (szczegółowe opisywanie wewnętrznych mechanizmów działania aplikacji mija się z celem), jednak powinien dać użytkownikowi wystarczająco dużo informacji, by mógł on świadomie wykorzystywać odpowiednie funkcje programu do realizacji postawionych przed nim zadań.

Rysunek 17.3. Przykład opisu koncepcyjnego – plik pomocy systemu C++Builder

Pomoc instruktażowa

Zadaniem materiałów instruktażowych jest, jak sama nazwa wskazuje, nauczenie użytkownika metod korzystania z programu. Z tego też względu dokumentacja taka musi zawierać liczne wyjaśnienia celu operacji oraz szczegółowe opisy zagadnień i terminów (zobacz rysunek 17.4). Istotne jest także poinformowanie użytkownika o celu wykładu lub ćwiczenia. Dobrze zaprojektowane dokumenty instruktażowe zawierają także rozbudowane, szczegółowo opisane przykłady i instrukcje, opisujące krok po kroku sposób ich wykonania. Bezpośrednim wyznacznikiem „jakości dydaktycznej” dokumentu jest adekwatność przykładu do zadań wykonywanych w praktyce przez użytkownika. W odróżnieniu od opisów proceduralnych materiały instruktażowe powinny być możliwie najbardziej dosłowne i szczegółowe.

Rysunek 17.4. Przykład opisu instruktażowego – HTML Help Workshop

Formaty plików pomocy

Nazwą „plik pomocy” (ang. help file) określa się odpowiednio sformatowany plik, zawierający dokumentację produktu, wyświetlaną na ekranie przez odpowiedni program. Używane obecnie formaty plików pomocy opisano w tabeli 17.1.

Tabela 17.1. Najpopularniejsze formaty plików pomocy

Oprócz opisanych powyżej w użyciu znajduje się wiele innych formatów plików pomocy, nie mających zastosowania do aplikacji tworzonych w C++Builderze. Jako przykłady można tu wymienić formaty Windows CE, Oracle oraz standardy wykorzystywane w systemach Linux i Unix.

WinHelp – sprawdzony standard

Pomimo bogactwa konkurencyjnych formatów, szerokie możliwości i łatwość rozpowszechniania wciąż czynią standard WinHelp najlepszym rozwiązaniem dla większości aplikacji tworzonych w systemie C++Builder. Pliki pomocy zapisane w formacie WinHelp dają się wykorzystywać we wszystkich wersjach systemu Windows (z 16-bitowej wersji 3. można korzystać nawet w systemie Windows 3.1), a wachlarz dostępnych narzędzi do ich tworzenia (również bezpłatnych) jest bardzo obszerny. System WinHelp jest stopniowo wypierany z rynku przez format HTML Help, wprowadzony w systemie Windows 98 i obsługiwany standardowo również w Windows 2000 i Millennium, a także w pakiecie Microsoft Office 2000. Najnowsza wersja standardu, HTML Help 1.3 (udostępniona w Windows 2000), dysponuje sporymi możliwościami, jest jednak trudniejsza w instalacji w systemach innych niż Windows 2000 (jej wykorzystanie wymaga np. obecności w systemie przeglądarki Internet Explorer w wersji co najmniej 4.0).

Z punktu widzenia naszej dyskusji najważniejszą różnicą pomiędzy standardami WinHelp i HTML Help jest zakres ich obsługi w systemie C++Builder. Wszystkie właściwości i metody komponentów VCL związane z obsługą systemu pomocy zorient...