Streszczenie rozprawy doktorskiej

Politechnika Poznańska
Wydział Informatyki
Automatyczne generowanie instrukcji obsługi dla
aplikacji internetowych
Bartosz Alchimowicz
Streszczenie rozprawy doktorskiej
Promotor:
Promotor pomocniczy:
dr hab. inż. Jerzy Nawrocki
dr inż. Mirosław Ochodek
Poznań, 2015
Spis treści
1
Wprowadzenie
1
2
Model jakości COCA dla dokumentacji użytkownika
3
2.1
Wprowadzenie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
2.2
Założenia do modelu jakości . . . . . . . . . . . . . . . . . . . . . . . . .
4
2.3
Model jakości COCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
2.3.1
Ocena . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
2.3.2
Profil jakości dla instrukcji obsługi . . . . . . . . . . . . . . . . .
5
2.4
Empiryczna ocena operowalności . . . . . . . . . . . . . . . . . . . . . .
6
2.5
Wnioski . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8
3
4
Automatyczne wyjaśnienie składni pól w aplikacjach internetowych
10
3.1
Wprowadzenie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2
Opis problemu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3
Generowanie opisów słownych . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4
Generowanie przykładów . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.5
Ocena eksperymentalna . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.6
Wnioski . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Ponowne użycie artefaktów do automatycznego generowania instrukcji
15
obsługi
4.1
Wprowadzenie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2
Zawartość wygenerowanej instrukcji obsługi . . . . . . . . . . . . . . . . 16
4.2.1
Komponenty instrukcji obsługi . . . . . . . . . . . . . . . . . . . 16
4.2.2
Warianty instrukcji obsługi . . . . . . . . . . . . . . . . . . . . . . 17
4.2.3
Analiza kompletności . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.3
Uniwersalne artefakty w projektach programistycznych . . . . . . . . . 18
4.4
Generowanie instrukcji obsługi . . . . . . . . . . . . . . . . . . . . . . . . 18
4.5
Naiwna instrukcja obsługi . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
I
II
4.6
Wymagania dotyczace
˛ środowiska pracy . . . . . . . . . . . . . . . . . . 20
4.7
Przykłady użycia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.8
Wst˛epna ocena . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.9
5
4.8.1
Badania wst˛epne . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.8.2
Ocena empiryczna . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Wnioski . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Podsumowanie
Bibliografia
25
27
Rozdział 1
Wprowadzenie
Instrukcje obsługi sa˛ jednym z artefaktów powstajacych
˛
podczas projektów programistycznych. Ich celem jest “opisanie, wyjaśnianie oraz poinstruowanie jak należy
poprawnie używać oprogramowania” [17, 19]. Cel ten osiaga
˛ si˛e poprzez stworzenie
dokumentacji dla ludzi pełniacych
˛
specyficzne role podczas korzystania z aplikacji
(np. instrukcja obsługi może zawierać rozdziały dedykowane różnym użytkownikom,
np. rozdział dla głównego ksi˛egowego czy kierownika magazynu, itd.).
Stworzenie wysokiej jakości dokumentacji jest kosztownym i czasochłonnym zadaniem [24, 40]. Wg Jonesa na każdy oszacowany punkt funkcyjny konieczne jest
napisanie 0.425 strony dokumentu [24], podczas gdy w materiałach opracowanych
przez SUN Technical Publications mowa jest o 3-5 godzin potrzebnych na stworzenie
jednej strony instrukcji [40]. Niestety, powszechna presja czasu i dażenie
˛
do minimalizacji kosztów umniejsza zadania inne niż rozwój kodu aplikacji. Sytuacja jest
dodatkowo utrudniona przez niskie ponowne użycie wcześniej napisanych tekstów.
Wg badań Jonesa tylko 15% dokumentacji może być ponownie użyta, podczas gdy powtórne użycie kodów szacuje si˛e na ok 36% (w zależności od j˛ezyka programowania)
[40].
Niska jakość instrukcji obsługi jest przyczyna˛ cz˛estego niezadowolenia użytkowników aplikacji. Irytacja klientów nie jest jedynym problemem, braki w instrukcjach
moga˛ przyczynić si˛e również do strat finansowych. Np. brak instrukcji lub jej niska jakość może spowodować, że firma b˛edzie zmuszona do zorganizowania dodatkowych
szkoleń. Ponadto pracownik, który nie jest w stanie sam rozwiazać
˛
problem najprawdopodobniej b˛edzie zmuszony do szukania pomocy gdzie indziej. W rezultacie może
przeszkodzić innym pracownikom w ich obowiazkach,
˛
a tym samym zmniejszy produktywność firmy. Podobny problem może zaistnieć kiedy dost˛epna funkcjonalność
oprogramowania nie jest wystarczajaco
˛ objaśniona, np. kiedy użytkownik nie jest
ostrzeżony o konsekwencjach użycia pewnych poleceń.
1
Wprowadzenie
2
Niespodziewane straty nie sa˛ ograniczone tylko do klientów. Użytkownik końcowy
cz˛esto prosi o pomoc producenta produktu, co wpływa na zwi˛ekszenie kosztów obsługi klienta. Co wi˛ecej, opisanie w instrukcji funkcjonalności, która nie jest dost˛epna
w oprogramowaniu, może być zgłoszona jako bład
˛ w aplikacji. Wszystko to może
wpłynać
˛ negatywnie na budżet producenta oraz na opini˛e odnośnie produktu.
Aby podnieść jakość instrukcji obsługi postawiono nast˛epujace
˛ pytanie:
P YTANIE 1. Czy jest możliwym wygenerowanie instrukcji obsługi dla aplikacji internetowych, których jakość przypominałaby teksty tworzone przez człowieka?
Termin instrukcja obsługi odnosi si˛e do różnego typu dokumentów, dlatego zdecydowano si˛e ograniczyć badania poprzez zdefiniowanie nast˛epujacego
˛
założenia:
Z AŁO ŻENIE 1. Instrukcja obsługi jest oceniona z punktu widzenia użytkownika końcowego.
W pracy zdecydowano skupić si˛e na użytkownikach końcowych, gdyż zdaja˛ si˛e
oni najwi˛eksza˛ grupa˛ osób korzystajacych
˛
z aplikacji. Ludzie ci cz˛esto posiadaja˛ ograniczona˛ wiedz˛e lub doświadczenie komputerowe, dlatego też dobrze napisany tekst
wydaje si˛e być korzystny zarówno dla nich, jak i dla producentów oprogramowania.
Współczesne aplikacje internetowe używaja˛ formularzy (b˛edacych
˛
zbiorem pól)
jako sposobu wprowadzenia danych od użytkownika. Oczekuje si˛e, iż użytkownik wpisze dane (tekst) w określone pole. Niektóre z pól posiadaja˛ skomplikowana˛ składni˛e,
która powinna być odpowiednio wyjaśniona użytkownikowi (np. w HTML5 istnieje
atrybut nazywany “tytuł”, który zawiera tekst wyświetlany użytkownikom końcowym).
“Objaśnienia pól” opisuja˛ jak wyglada
˛ składnia danych wejściowych.
Z AŁO ŻENIE 2. Dokumentacja użytkownika zawiera instrukcj˛e obsługi i objaśnienia
pól.
Model jakości jest potrzebny aby porównać jakość dwóch instrukcji obsługi, dlatego postawiono nast˛epujace
˛ pytania:
P YTANIE 2. Które kryteria oceny powinny być brane pod uwag˛e podczas analizy
jakości instrukcji obsługi?
P YTANIE 3. Jaka jest jakość przeci˛etnej komercyjnej instrukcji obsługi?
P YTANIE 4. Jakie elementy powinny być opisane w instrukcji obsługi?
W pracy wzi˛eto pod uwag˛e także problemy j˛ezykowe:
Z AŁO ŻENIE 3. Praca skupia si˛e na generowaniu w j˛ezyku angielskim, jednakże kwestie wieloj˛ezyczności sa˛ również rozważane (szczególnie dla j˛ezyka polskiego).
Rozdział 2
Model jakości COCA dla
dokumentacji użytkownika
2.1 Wprowadzenie
Instrukcja obsługi o dobrej jakości może przynieść korzyści zarówno producentom
oprogramowania jak i użytkownikom. Według Fishera [11], projekt programistyczny
można nazwać udanym jeśli, program działa zgodnie z oczekiwaniami oraz użytkownicy sa˛ zadowoleni. Z punktu widzenia użytkownika końcowego oczekiwane działanie
programu powinno być opisane w instrukcji obsługi. Stad
˛ też, z punktu widzenia
Fishera, wybrakowana instrukcja (np. taka, która jest niespójna z oprogramowaniem)
ma efekt podobny do wadliwego oprogramowania (niezgodnego ze specyfikacja)
˛ —
obie sytuacje prowadza˛ do frustracji użytkownika, co zmniejsza jego zadowolenie z
programu. Dodatkowo, Pedraz-Delhaes i inni [34] podkreślaja,
˛ że użytkownicy na
podstawie dostarczonej dokumentacji oceniaja˛ zarówno produkt, jak i producenta.
Według danych zebranych przez Spencera [39], dobrej jakości instrukcja obsługi
może zmniejszyć liczb˛e rozmów telefonicznych działu obsługi klienta z 641 do 59 w
przeciagu
˛ 5-miesi˛ecy (w 2008 średni koszt pojedynczej rozmowy z działem obsługi
klienta wynosił $32 [26]).
Niestety użytkownicy końcowi cz˛esto sa˛ niezadowoleni z jakości instrukcji. Narzekaja˛ na skomplikowany j˛ezyk, nudne opisy, nieaktualne lub bezużyteczne informacje
[28, 29]. Co wi˛ecej, niektórzy użytkownicy czuja˛ si˛e sfrustrowani używajac
˛ oprogramowania [13].
Tak wi˛ec dobrej jakości instrukcja obsługi jest potrzebna. Stad
˛ też pojawia si˛e pytanie co w tym kontekście oznacza dobra jakość oraz jakiego rodzaju charakterystyki
powinny być rozważane przy ocenianiu jakości instrukcji.
3
2.2. Założenia do modelu jakości
4
2.2 Założenia do modelu jakości
Według Standardu ISO 25000:2005 [15], model jakości jest to zbiór powiazanych
˛
ze
soba˛ charakterystyk, które to stanowia˛ podstaw˛e do opracowania wymagań jakościowych i oceny jakości.
Model jakości opisany w niniejszej pracy zorientowany jest na dokumentacj˛e
użytkownika, rozumianej jako dokumentacj˛e systemu dla użytkowników, zawierajacej
˛
opis systemu oraz procedur jego użycia do uzyskania zamierzonego rezultatu [19].
Poniżej przedstawiono założenia dotyczace
˛ modelu jakości:
Z AŁO ŻENIE 1. Zakłada si˛e, iż dokumentacja użytkownika jest przedstawiona w formie statycznej (np. pliku PDF).
Z AŁO ŻENIE 2. Zakłada si˛e, iż instrukcja obsługi jest oceniona z punktu widzenia
użytkownika końcowego.
Z AŁO ŻENIE 3. Model jakości dla dokumentacji użytkownika może zostać ograniczony
do external quality oraz quality-in-use.
Z AŁO ŻENIE 4. Dokumentacja użytkownika ma wspierać użytkownika w wykonywaniu zadań biznesowych.
Z AŁO ŻENIE 5. Dobry model jakości dla dokumentacji użytkownika powinien być
ortogonalny.
Z AŁO ŻENIE 6. Dobry model jakości dla dokumentacji użytkownika powinien być
kompletny z punktu widzenia użytkownika końcowego.
2.3 Model jakości COCA
Model jakości COCA prezentuje punkt widzenia użytkownika końcowego odnośnie
jakości instrukcji obsługi. Proponowany model zawiera cztery charakterystyki jakości:
Completeness (kompletność), Operability (operowalność), Correctness (poprawność)
i Appearance (wyglad).
˛
Cechy te sa˛ zdefiniowane poniżej:
D EFINICJA 1. Kompletność jest to stopień, w którym dokumentacja użytkownika
dostarcza wszystkie informacje potrzebne użytkownikowi końcowemu do użycia opisanego oprogramowania.
D EFINICJA 2. Operowalność sensu stricto (Operowalność w ścisłym znaczeniu) określa
stopień w jakim dokumentacja użytkownika posiada atrybuty, które to pozwalaja˛
2.3. Model jakości COCA
5
UC: Ocena instrukcji obsługi
Scenariusz główny:
1. Lider przegladu
˛ tworzy, na polecenie Osoby decyzyjnej, Evaluation Mandate.
Tworzy również Evaluation Forms .
2. Eksperci oceniaja˛ dokumentacj˛e użytkownika z punktu widzenia charakterystyk jakości im przypisanych (np. Kompletność i Poprawność) a także
wypełniaja˛ Evaluation Forms.
3. Lider przegladu
˛ otrzymuje Evaluation Forms.
4. Potencjalni użytkownicy oceniaja˛ dokumentacj˛e użytkownika pod katem
˛
cech jakości im przypisanych (np. Operowalność i Wyglad)
˛ i uzupełniaja˛
Evaluation Forms.
5. Lider przegladu
˛ gromadzi Evaluation Forms, analizuje zabrane informacje
i tworzy Evaluation Report .
Rozszerzenia:
3.A. Ocena Ekspertów jest negatywna.
3.A.1. Przejdź do punktu 5.
Rysunek 2.1: Procedury oceny dokumentacji użytkownika
użyć ja˛ w sposób prosty oraz ułatwiaja˛ zdobywanie wiedzy zawartej w dokumentacji
użytkownika.
D EFINICJA 3. Poprawność jest to stopień w jakim opisy zawarte w dokumentacji
użytkownika sa˛ poprawne.
D EFINICJA 4. Wyglad
˛ jest to stopień w którym informacje zawarte w dokumentacji
użytkownika sa˛ przedstawione w estetyczny sposób.
2.3.1 Ocena
Czynności potrzebne do oceny dokumentacji użytkownika sa˛ przedstawione (w formie przypadku użycia [7]) na Rysunku 2.1.
2.3.2 Profil jakości dla instrukcji obsługi
Aby zdecydować czy można zaprezentować użytkownikom końcowym dokumentacj˛e
użytkownika zaleca si˛e porównanie danej dokumentacji użytkownika z innymi do-
6
2.4. Empiryczna ocena operowalności
Tablica 2.1: Lista ocenionych instrukcji obsługi (strony sa˛ liczone bez okładki i spisu
treści; ostatnia kolumna przedstawia liczb˛e Ekspertów i Potencjalnych użytkowników
uczestniczacych
˛
w ewaluacji)
Nazwa
Plagiat.pl – Instrukcja użytkownika indywidualnego
Podstawy obsługi Dziekanatu.XP
Sekretariat Optivum – Podr˛ecznik użytkownika programu
Instrukcja obsługi Platformy nSzkoła – Panel Ucznia
Sekretariat DDJ 6.8
LangSystem 4.2.5 – Dokumentacja użytkownika
School Manager – Podr˛ecznik użytkownika
Instrukcja obsługi aplikacji HERMES 2012
Dziennik elektroniczny e-oceny
Liczba Eksperci/
stron Użytkownicy
13
3/16
19
3/17
25
3/17
16
3/16
21
3/16
22
3/17
27
3/17
21
3/16
23
3/16
kumentacjami opracowanymi przez dana˛ organizacj˛e lub innymi dokumentacjami
dost˛epnymi na rynku. Zamiast porównywać dokumenty r˛ecznie jedno po drugim,
proponuje si˛e opracowanie profilu jakościowego, który to prezentuje uśrednione
wartości.
W celu sprawdzenie zaproponowanego podejścia, przeprowadzono badanie, którego cel był nast˛epujacy:
˛
Analiza zestawu instrukcji obsługi w celu stworzenia profilu jakości z
punktu widzenia użytkowników końcowych i w kontekście w którym rol˛e
użytkowników końcowych przej˛eli studenci a rol˛e Ekspertów wykładowcy
i doktoranci.
W celu opracowania profilu jakości poddano ocenie 9 instrukcji obsługi (patrz
Tabela 2.1). Każda z charakterystyk została oceniona poprzez udzielenie odpowiedzi
na pytania przyporzadkowane
˛
do charakterystyk (patrz Tabela 2.2). Na każde z pytań
uczestnicy mogli wybrać jedna˛ z nast˛epujacych
˛
odpowiedzi: Wcale (N), Słabo (w),
trudno powiedzieć (?), wystarczajaco
˛ (g), bardzo dobrze (VG). Przykładowy profil
dla instrukcji obsługi opisujacych
˛
oprogramowanie używane w szkolnictwie został
przedstawiony w Tabeli 2.3.
2.4 Empiryczna ocena operowalności
Aby ocenić instrukcje obsługi eksperymentalnie można użyć metod˛e Browser Evaluation Test [42]. Metoda ta została stworzona do oceniania jakości przegladarek
˛
nagrań spotkań. Podczas oceny jakości, każdemu uczestnikowi przedstawiona jest
2.4. Empiryczna ocena operowalności
7
Tablica 2.2: Przykładowe pytania dla metody COCA oraz ich przyporzadkownie
˛
do
charakterystyk
Pytanie
Kompletność
• W jakim stopniu dokumentacja użytkownika pokrywa cała˛ funkcjonalność
systemu z wymaganym poziomem szczegółowości?
• W jakim stopniu dokumentacja użytkownika dostarcza informacje pomocne w podj˛eciu decyzji czy system odpowiedna potrzeb potencjalnych
użytkowników?
• W jakim stopniu dokumentacja użytkownika zawiera informacje o tym jak
z niej korzystać w sposób skuteczny i efektywny?
Operowalność
• W jakim stopniu dokumentacja użytkownika jest łatwa w użyciu i pomocna
podczas obsługi systemu udokumentowanego przez nia?
˛
Poprawność
• W jakim stopniu dokumentacja użytkownika dostarcza poprawne opisy z
wymaganym poziomem szczegółowości?
Wyglad
˛
• W jakim stopniu informacje zawarte w dokumentacji użytkownika prezentowane sa˛ w estetyczny sposób?
lista dopełniajacych
˛
si˛e twierdzeń (jedno prawdziwe i jedno fałszywe). Zadaniem
uczestnika jest wskazanie prawdziwego twierdzenia (np. jedno z nich może być Susan
mówi, że stołek nie jest drogi, a drugie Susan mówi, że stołek jest drogi [42]). Poprzez
proste zgadywanie można odgadnać
˛ około 50% poprawnych odpowiedzi, co nie jest
akceptowalne z naszego punktu widzenia. Aby temu zaradzić, opracowano wariant
BET nastawiony na ocen˛e instrukcji obsługi i nazwano go Documentation Evaluation
Test (DET) — metoda ta ogranicza możliwość odgadni˛ecia poprawnych odpowiedzi
do około 25% poprzez zadanie 4 pytań. Procedura DET jest zaprezentowana na Rysunku 2.2. W celu sprawdzenie opracowanej metody przeprowadzono eksperyment,
którego cel był nast˛epujacy:
˛
Analiza instrukcji obsługi w celu oceny jakości z uwaga˛ skierowana˛ na
Operowalność, z punktu widzenia użytkowników końcowych w kontekście
doktorantów odgrywajacych
˛
rol˛e Ekspertów i studentów jako Potencjalnych użytkowników.
8
2.5. Wnioski
Tablica 2.3: Przykładowy profil jakości
Id Pytanie
N
w
?
g
VG
Kompletność
odpowiedzialny: Ekspert
3.7%
18.5%
29.6% 44.4% 3.7%
Q1 W jakim stopniu dokumentacja użytkownika
pokrywa cała˛ funkcjonalność systemu z wymaganym poziomem szczegółowości?
Q2 W jakim stopniu dokumentacja użytkownika 0.0% 3.7% 11.1% 55.6% 29.6%
dostarcza informacje pomocne w podj˛eciu decyzji czy system odpowiedna potrzeb potencjalnych użytkowników?
odp.: Potencjalny użytkownik
Q3 W jakim stopniu dokumentacja użytkownika 6.1% 9.5% 7.4% 50.0% 27.0%
zawiera informacje o tym jak z niej korzystać
w sposób skuteczny i efektywny?
Operowalność
odp.: Potencjalny użytkownik
Q4 W jakim stopniu dokumentacja użytkownika 1.4% 6.8% 14.9% 48.0% 29.1%
jest łatwa w użyciu i pomocna podczas obsługi
systemu udokumentowanego przez nia?
˛
Poprawność
odp.: Ekspert
0.0%
18.5%
25.9%
44.4% 11.1%
Q5 W jakim stopniu dokumentacja użytkownika
dostarcza poprawne opisy z wymaganym poziomem szczegółowości?
Wyglad
˛
odp.: Potencjalny użytkownik
Q6 W jakim stopniu informacje zawarte w doku- 1.4% 12.2% 12.2% 49.3% 25.0%
mentacji użytkownika prezentowane sa˛ w estetyczny sposób?
Eksperyment został zaprojektowany podobnie do tego przedstawionego w cz˛eści
2.3.2. Przeanalizowano pi˛eć instrukcji obsług, których wyniki pokazano w Tabeli
2.4. Wszystkie instrukcje zostały wcześniej sprawdzone przez Ekspertów pod katem
˛
Kompletności i Poprawności (rola ta była odegrana przez nauczycieli akademickich i
doktorantów).
2.5 Wnioski
Przedstawiono model oceny jakości COCA. Zawiera on tylko cztery charakterystyki:
kompletność, operowalność, poprawność i wyglad.
˛ Model jest uznany za ortogonalny i kompletny. Opracowano profil jakości poprzez ocen˛e dziewi˛eciu instrukcji
obsług dost˛epnych na polskim rynku. Chociaż ocena dotyczy oprogramowania komercyjnego, ich jakość nie jest zbyt wysoka. Na przykład, tylko w 48.1% Ekspertów
oceniło instrukcje jako dobre lub bardzo dobre. W przypadku metody DET, Eksperci
9
2.5. Wnioski
UC: Documentation Evaluation Test
Scenariusz główny:
1. Eksperci indywidualnie czytaja˛ instrukcje obsługi, tworza˛ Pytania i przekazuja˛ je Liderowi przegladu.
˛
˛ czyści Pytania przekazane od Ekspertów (np. usuwa dupli2. Lider przegladu
katy, poprawia pisowni˛e, itd.).
3. Lider przegladu
˛ przygotowuje Test poprzez losowy wybór Pytań.
4. Potencjalni użytkownicy, aby ocenić Operowalność, wypełniaja˛ Test korzystajac
˛ z instrukcji obsługi.
5. Lider przegladu
˛ pisze Raport dotyczacy
˛ instrukcji obsługi.
Rozszerzenia:
˛ dochodzi do wniosku, że liczba Pytań jest niewystarcza3.A. Lider przegladu
jaca.
˛
˛ prosi dodatkowego Eksperta o wykonanie kroku 1.
3.A.1. Lider przegladu
Rysunek 2.2: Procedura oceny metoda˛ DET
tworza˛ 1.5 pytania na stron˛e, a procent poprawnych odpowiedzi udzielonych przez
Potencjalnych użytkowników wynosi od 77% do 87%.
Tablica 2.4: Wyniki oceny metoda˛ DET
Instrukcja
obsługi
Plagiat.pl
Dziekanat.XP
Sekretariat Optivum
LangSystem
Hermes
Suma
Liczba
Liczba
uczestników stron
16
17
17
17
16
83
Średni
Liczba Średni procent
czas
Pytań poprawnych
odpowiedzi [min]
odpowiedzi
13
39
29
82.97%
19
40
28
86.97%
25
61
30
76.47%
22
52
30
81.76%
21
52
28
77.01%
100
244
145
Rozdział 3
Automatyczne wyjaśnienie składni
pól w aplikacjach internetowych
3.1 Wprowadzenie
Aplikacje internetowe cz˛esto wymagaja˛ wprowadzenia tekstu (ciagu
˛ znaków) w pola
formularzy. Niestety, składnia tych pól cz˛esto nie jest przedstawiona. Nie jest to
problem dla typowych ciagów
˛
znakowych, jak np. nazwa użytkownika czy wiek.
Istnieja˛ jednak pola, które stanowia˛ wyzwanie dla użytkownika końcowego, jak np.
ISBN, ISSN. Aby pomóc użytkownikom można umieścić opisy składni pól w aplikacji
lub w instrukcji obsługi. Jednakże złożone pola nie pojawiaja˛ si˛e cz˛esto i zdarza si˛e,
iż ich opisy sa˛ pomijane, co w konsekwencji pozostawia użytkowników bez pomocy.
Rozwiazaniem
˛
tego problemu może być automatyczna generacja objaśniania pola na
podstawie informacji dost˛epnych w kodzie źródłowym.
Niniejszy rozdział rozważa możliwość generowania objaśnienia pola na podstawie
wyrażenia regularnego. Praca ta rozszerza poprzednie badania prowadzone przez
Alchimowicza i Nawrockiego [3], które to skupiały si˛e na graficznej reprezentacji
wyrażeń.
3.2 Opis problemu
Niniejszy rozdział dotyczy nast˛epujacego
˛
problemu badawczego:
P ROBLEM 1. Biorac
˛ pod uwag˛e opis pola składajacego
˛
si˛e z jego nazwy i składni
opisanej przy pomocy wyrażenia regularnego, wygeneruj opis objaśniajacy
˛ składni˛e
pola. Wygenerowane objaśnienie powinno być tak samo pomocne jak to napisane
przez człowieka.
10
11
3.3. Generowanie opisów słownych
VAT is described by the following diagram:
VAT consists of 3 digits, a hyphen (-), two Ingredients and three digits.
An Ingredient consists of two digits and a hyphen (-).
Example
948-93-00-158
195-19-75-984
793-28-87-441
563-328
23987-58-87-441
Correct?
Yes
Yes
Yes
No (absence of Header)
No (too long)
Rysunek 3.1: Przykład 3-cz˛eściowego opisu
Dodatkowo postawiono nast˛epujace
˛ wymagania:
W YMAGANIE 1. Wygenerowany opis powinien być dost˛epny w wielu j˛ezykach.
U ZASADNIENIE . J˛ezyk angielski jest bardzo popularnym j˛ezykiem, ale wiele aplikacji
internetowych nadal jest używanych przez ludzi preferujacych
˛
j˛ezyk rodzimy. Dlatego
też pomocne byłoby, aby generator wspierał wiele j˛ezyków. Obecna wersja wspiera
j˛ezyk angielski i polski.
Z AŁO ŻENIE 1. Wygenerowane objaśnienie powinno zawierać opis słowny, graficzna˛
reprezentacj˛e wyrażenia regularnego (oparta˛ na koncepcji diagramów składni [3])
oraz zestaw przykładów (z poprawnymi i niepoprawnymi danymi wejściowymi).
W dalszej cz˛eści pracy ten typ objaśnienia nazwany b˛edzie 3-cz˛eściowym opisem.
U ZASADNIENIE . Istotność założeń została potwierdzona poprzez empiryczna˛ ocen˛e
prezentowanych metod (patrz Rozdział 3.5). Jednakże, dalsze badania b˛eda˛ konieczne, aby sprawdzić ważność każdej z trzech cz˛eści opisu.
Na przykład, dla pola VAT, którego składnia jest opisywana przez nast˛epujace
˛
wyrażenie:
VAT = [0-9]{3}-([0-9]{2}-){2}[0-9]{3}
możnaby otrzymać opis (w j˛ezyku angielskim) przedstawiony na Rysunku 3.1.
3.3 Generowanie opisów słownych
Generowanie objaśnień pól jest swojego rodzaju tłumaczeniem, a reguły generowania moga˛ być opisana jako syntax-directed definitions [2]. W celu wygenerowania
12
3.3. Generowanie opisów słownych
Zero = " 0 "
PL (): " zero "
;
Rysunek 3.2: Prosta reguła generowania.
Tablica 3.1: Przykładowe reguły sprawdzania czy pole akceptuje pusty ciag
˛ znaków
Wyrażenie regularne r
r1∗
r1?
r1+
r 1 {a, b}
r 1 |..|r n
r 1 ..r n
² in L(r )
true
true
iff ² in L(r 1 )
iff (a = 0) or (² in L(r 1 ))
iff there exists j : 1 ≤ j ≤ n • ² in L(r j )
iff for every j : 1 ≤ j ≤ n • ² in L(r j )
objaśnień, opracowano zestaw reguł. Rysunek 3.2 prezentuje prosta˛ reguł˛e, która˛ dla
cyfry 0 zwraca tekst zero. W pracy użyto zapis bazujacy
˛ na EBNF [14].
Zakłada si˛e, iż opis słowny b˛edzie stworzony przy pomocy szablonów generowania tekstu, które to b˛eda˛ si˛e nakładać (szablon może używać opisu wygenerowanego przez inny szablon). Takie podejście jest niezwykle atrakcyjne, lecz wymaga
uwzgl˛ednienia kontekstu podczas wstawiania danego szablonu. Informacje odnośnie
kontekstu przekazywane sa˛ do owych szablonów poprzez atrybuty gramatyczne.
Cz˛eść wyrażeń regularnych dopuszcza wprowadzenie pustego ciagu.
˛
Może to
prowadzić do wygenerowania opisów podobnych do nie puste opcjonalne ciagi
˛ ...,
co jest poprawnym opisem, ale niekoniecznie łatwym do zrozumienia. Ze wzgl˛edu
na zrozumiałość byłoby lepiej napisać wprost, iż dane pole można pozostawić puste. Na przykład, można by wygenerować objaśnienie w formie Możesz pozostawić
pole puste lub dokonać wpisu. . . . W celu usprawnienia czytelności opisu, wyrażenie
regularne sprawdzane jest pod katem
˛
możliwości przyjmowania pustych ciagów
˛
znaków. Jeżeli dane pole dopuszcza taka˛ sytuacj˛e, to generowany opis jest odpowiednio
usprawniany. Tabela 3.1 prezentuje przykładowych zestaw reguł.
Kolejny problem jest połaczony
˛
ze specyficzna˛ struktura˛ wyrażeń regularnych,
która nie jest odpowiednia dla bezpośredniego przekształcenia w j˛ezyk naturalny.
Na przykład, przy dosłownym przekształceniu nast˛epujacego
˛
wyrażenia regularnego
Seria = [0-9](","[0-9])+ możnaby stworzyć opis Seria jest ciagiem
˛
zawieraja˛
cym cyfr˛e dziesi˛etna,
˛ z nast˛epujacym
˛
po niej ciagiem
˛
składajacym
˛
si˛e z przecinka i
cyfry dziesi˛etnej. Co jest poprawne, ale znów nie do końca łatwe do zrozumienia.
Lepsze było by: Seria jest ciagiem
˛
co najmniej dwóch cyfr dziesi˛etnych oddzielonych
przecinkami. W tym celu wprowadzono idiomatic patterns, które to służa˛ do wykrywania zależności pomi˛edzy składnikami wyrażenia regularnego. Przykład wykrywania
13
3.4. Generowanie przykładów
takiej sytuacji i generowania opisu słownego prezentowany jest poniżej:
C o m p o n e n t 1= > F a c t o r 1 F a c t o r 2
&& F a c t o r 2
=> Primary "+"
&& P r i m a r y
=> "(" Regex ")"
&& R e g e x
=> Component2
&& C o m p o n e n t 2 = > F a c t o r 3 F a c t o r 4
&& F a c t o r 1
== F a c t o r 4
EN ( ): " a sequence of at least two " F a c t o r 1 < 2
" separated with " F a c t o r 3 < 2
;
Niektóre z wyrażeń regularnych sa˛ zbyt skomplikowane, by objaśnić je na jednym
diagramie lub opisać jednym zdaniem. Byłoby łatwiej, gdyby opis został rozbity na
kilka cz˛eści, np.
Index = [0 -9]+(\ +[0 -9]+)+
może zostać przepisane na
Number = [0 -9]+
Gap = \ +
Index = Number ( Gap Number )+
W ten sposób uzyskuje si˛e dodatkowe wyrażenia, które łatwiej opisać.
W niektórych przypadkach może dojść do wygenerowania nieczytelnych opisów.
W odniesieniu do nich, zdecydowaliśmy si˛e zastosować rozwiazanie
˛
podobne do
miecza Aleksandra, tzn. poprzez stworzenie i utrzymanie “czarnej listy” wyrażeń zbyt
trudnych do objaśnienia przy pomocy poprzedniego podejścia i dostarczyć dla nich
gotowy zestaw opisów.
3.4 Generowanie przykładów
Każde objaśnienie pola powinno być wzbogacone zbiorem przykładowych ciagów
˛
znakowych zawierajacy
˛ poprawne i niepoprawne wpisy. Ponadto, każdy niepoprawny
przykład powinien być uzupełniony opisem dlaczego został on uznany za bł˛edny
(Rysunek 3.1). Stad
˛ też pojawia si˛e nast˛epujacy
˛ problem:
P ROBLEM 2. Jak wygenerować przykłady niepoprawnych ciagów
˛
wejściowych, aby
móc wyjaśnić co jest bł˛edne w przedstawionych danych wejściowych?
W tym celu zaproponowano kontrolowane posiewanie bł˛edów w wyrażeniu regularnym. Proponuje si˛e dwa typy posiewania bł˛edów:
3.5. Ocena eksperymentalna
14
• Usuni˛ecie — pomini˛ecie jednego z czynników w wyrażeniu regularnym,
• Zanieczyszczenie — wstawienie zaburzenia w wyrażeniu regularnym.
Aby mieć pewność, że wygenerowane kontrprzykłady sa˛ odpowiednio dobrane,
każde ze zmodyfikowanych wyrażeń regularnych i stworzonych na ich podstawie
ciagów
˛
znakowych jest sprawdzane pod katem
˛
spełnienia nast˛epujacych
˛
warunków:
• Czy wykracza si˛e poza j˛ezyk opisany przez pierwotne wyrażenie regularne?
• Czy jest to nowy bł˛edny ciag
˛ znaków, który nie został poprzednio wykryty?
3.5 Ocena eksperymentalna
Aby stwierdzić czy wygenerowane opisy sa˛ nie gorsze niż objaśnienia przygotowane
przez ludzi stworzono prototyp narz˛edzia i przeprowadzono kontrolowany eksperyment. W tym celu wybrano pi˛eć wyrażeń regularnych opisujacych
˛
skomplikowane
pola oraz poproszono grup˛e 15 studentów oprogramowania o napisanie objaśnień
do nich. Nast˛epnie wygenerowane i stworzone przez studentów objaśnienia dano
do oceny 207 uczestnikom. Podczas eksperymentu otrzymano około 84% wyników
pozytywnych dla opisów wygenerowanych (procent poprawnie rozpoznanych ciagów
˛
znaków przez uczestników) oraz około 79% dla opisów stworzonych przez człowieka.
3.6 Wnioski
Celem pracy było zbadanie czy jest możliwym automatyczne wygenerowanie 3-cz˛eściowego opisu składni pól o jakości nie gorszej niż opisy stworzone przez człowieka.
Założono, że 3-cz˛eściowy opis powinien składać si˛e z nast˛epujacych
˛
elementów:
opisu słownego, reprezentacji graficznej, oraz zestawu przykładów (pozytywnych i
negatywnych).
Generowanie 3-cz˛eściowego opisu sterowane jest przy pomocy zestawu reguł
zapisanych w specjalnie zaprojektowanym j˛ezyku (DSL), który przypomina syntax-directed definition. Powstałe opisy moga˛ być w wielu jezykach oraz dostosowane do
potrzeb klienta, np. lingwista może dodać nowe opisy lub dodać zasady dla nowego
j˛ezyka.
Każdy opis słowny wzbogacony jest zbiorem przykładów i kontrprzykładów oraz
reprezentacja˛ graficzna.
˛ Aby otrzymać bł˛edny ciag
˛ znakowy, cz˛eść wyrażenia regularnego może być usuni˛eta lub też wyrażenie regularne może być zanieczyszczone w
“kontrolowany” sposób.
Rozdział 4
Ponowne użycie artefaktów do
automatycznego generowania
instrukcji obsługi
4.1 Wprowadzenie
Korzyści płynace
˛ z generowanych dokumentów zostały spostrzeżone przez Reitera
i innych [36]. Według ich badań, automatyczne podejście może zredukować koszty
tworzenia i utrzymania dokumentacji, zapewnić ciagłość
˛
pomi˛edzy produktem a
jego opisem, tworzyć tłumaczenia wieloj˛ezyczne, dostosować złożoność opisu do
wymagań odbiorcy oraz prezentować informacje w różnych formach (np. tekst lub
grafika). Pojawiaja˛ si˛e zatem pytania dotyczace
˛ możliwości oraz ograniczeń w zakresie
generowania instrukcji obsługi dla aplikacji internetowych:
P YTANIE 1. W jakim stopniu możliwe jest wygenerowanie instrukcji obsługi korzystajac
˛ z artefaktów dost˛epnych w projektach programistycznych?
P YTANIE 2. W jakim stopniu instrukcja obsługi wygenerowana na bazie dost˛epnych artefaktów spełnia kryteria stawiane przez model jakości COCA oraz metod˛e
Documentation Evaluation Test (DET)?
U ZASADNIENIE . Instrukcja obsługi (stworzona czy też przez człowieka, czy to przez
program) powinna spełniać wymogi dotyczace
˛ jakości. Do porównania jakości wygenerowanych instrukcji z tymi opracowanymi przez ludzi zdecydowano si˛e użyć
modelu oceny jakości COCA oraz metody DET [4]. Model jakości COCA pozwala na
ocen˛e jakości instrukcji obsługi z punktu widzenia czterech ortogonalnych charakterystyk: kompletności, operowalności, poprawności oraz wygladu.
˛
Metoda DET skupia
si˛e na ocenie operowalności.
15
4.2. Zawartość wygenerowanej instrukcji obsługi
16
Cel niniejszego rozdziału jest nast˛epujacy:
˛
C EL . Opracować zestaw metod umożliwiajacych
˛
generowanie instrukcji obsługi dla
aplikacji internetowych przeznaczonej dla laików komputerowych.
4.2 Zawartość wygenerowanej instrukcji obsługi
W nawiazaniu
˛
do celu pracy zaprezentowanego w Rozdziale 4.1, należy rozpatrzyć
nast˛epujac
˛ a˛ kwesti˛e:
P ROBLEM 1. Jakie informacje powinny być zawarte w instrukcji obsługi i jak powinny
być one zorganizowane?
W odniesieniu do elementów składowych instrukcji obsługi zostanie użyty termin
komponent, zgodnie z terminologia˛ użyta˛ w standardzie ISO/IEC 26514:2008 [17].
4.2.1 Komponenty instrukcji obsługi
Aby określić zawartość i struktur˛e instrukcji obsługi przeprowadzono analiz˛e dost˛epnej literatury i materiałów. Przeglad
˛ literatury uwzgl˛ednił publikacje naukowe (m.in.:
[28, 29, 37]), rekomendacje ([9, 10, 40]) oraz standardy ([6, 17, 18, 20, 21, 22]). Analiza
instrukcji obsługi obejmowała 9 dokumentów użytych do stworzenia profilu jakości
COCA [4].
Zdecydowano, że wygenerowana instrukcja obsługi powinna składać si˛e z nast˛epujacych
˛
komponentów:
• Okładka (ang. Cover)—pozwala czytelnikowi zidentyfikować instrukcj˛e obsługi.
Okładka może zawierać nazw˛e aplikacji i jej wersj˛e, wersj˛e instrukcji obsługi,
nazw˛e firmy, itd. Z tyłu okładki można umieścić Mi˛edzynarodowy Standardowy
Numer Ksiażki
˛ (ISBN) oraz inne użyteczne informacje.
• Spis treści (ang. Table of contents)—przedstawia komponenty wraz z numerami
stron. Moga˛ pojawić si˛e różnego rodzaju spisy, np. spis rozdziałów, wykresów,
tablic, słów kluczowych, itd.
• Ostrzeżenia i uwagi (ang. Warning and Notices)—prezentuje ostrzeżenia, uwagi,
informacje wymagane przez prawo, itd.
• Konwencje (ang. Conventions)—opisuje konwencje użyte w instrukcji obsługi.
• Wprowadzenie (ang. Introduction)—przedstawia koncepcj˛e i ide˛e stojac
˛ a˛ za
aplikacja,
˛ problemy i sposób w jaki oprogramowanie pomaga je rozwiazać.
˛
17
4.2. Zawartość wygenerowanej instrukcji obsługi
Wariant
Naiwna instrukcji obsługi
Kompletna instrukcja obsługi
Komponent
Okładka
Spis treści
Ostrzeżenia i uwagi
Konwencje
Wprowadzenie
Wymagania dotyczace
˛ środowiska pracy
Obiekty informacyjne
Zadania:
Aktorzy
Scenariusze
Przykłady
Słownik
—
—
—
Tablica 4.1: Warianty instrukcji obsługi
• Wymagania dotyczace
˛ środowiska pracy (ang. Requirements concerning operating environment)—prezentuje wymagania, które użytkownik musi spełnić
by korzystać z aplikacji (np. typ i wersj˛e przegladarki).
˛
• Obiekty informacyjne (ang. Information objects)—przedstawia dane, które
użytkownik tworzy, pobiera, uaktualnia oraz kasuje korzystajac
˛ z opisywanej
aplikacji.
• Zadania (ang. Tasks)—prezentuje cele jakie można osiagn
˛ ać
˛ przy pomocy
aplikacji oraz opisuje jak je zrealizować.
• Słownik (ang. Glossary)—wyszczególnia i objaśnia terminy użyte w aplikacji.
4.2.2 Warianty instrukcji obsługi
Używajac
˛ komponentów z Rozdział 4.2.1 można stworzyć wiele odmian instrukcji
obsługi (np. aby dostosować zawartość do odbiorcy). Proponujemy dwie wersje:
kompletna instrukcja obsługi (korzystajac
˛ ze wszystkich elementów w cz˛eści 4.2.1)
oraz naiwna instrukcja obsługi (korzystajac
˛ z jak najmniejszej liczby elementów)—
patrz Tabela 4.1.
4.2.3 Analiza kompletności
W celu sprawdzenia czy informacje wymagane przez czytelnika sa˛ dost˛epne w wygenerowanej instrukcji obsługi przeprowadzono porównanie zaproponowanych komponentów z rekomendacjami standardu ISO/IEC 26514:2008 [17] i wytycznymi przedstawionymi w ksiażce
˛
Read Me First! (wydanej przez Sun Technical Publishing [40]).
Wynik porównania przedstawiony jest w Tabeli 4.2.
Z porównania wynika, że zaproponowane komponenty spełniaja˛ wymagania i
zalecenia wspomnianych opracowań.
18
4.3. Uniwersalne artefakty w projektach programistycznych
ISO/IEC Std 26514:2008 [17]
Komponenty wymagane i/lub zalecane
Identification data
Identification data
Table of contents
Introduction
Information for use of the documentation
Concept of operations
Procedures
Error messages and problem resolution
Glossary
Index
Komponenty opcjonalne
List of illustrations
Related information sources
Sun Technical Publishing [40]
Komponent 4.2.1
Title page
Legal notice
Table of contents
Preface
Preface
Preface
(content of a) Chapter
Index
Cover
Warning and Notices
Table of contents
Introduction
Conventions
Introduction
Tasks (Scenarios)
Tasks (Examples)
Glossary
Table of contents
List of figures
List of tables
List of examples
Chapter table of contents
Appendixes
Glossary
Bibliography
Revision history
Table of contents
Table of contents
Table of contents
Table of contents
—
Glossary
—
—
Tablica 4.2: Porównanie komponentów rekomendowanych w standardzie ISO/IEC
26514:2008 (wersja paper based, instructional mode) [17] i Sun Technical Publishing
(wersja z wieloma rozdziałami) [40], z komponentami dost˛epnymi w kompletnej
instrukcji obsługi (zachowano oryginalne nazewnictwo w j˛ezyku angielskim).
4.3 Uniwersalne artefakty w projektach programistycznych
Zamiast wymagać tworzenia nowych artefaktów proponujemy ponowne użycie już
istniejacych;
˛
stad
˛ też rozpatrujemy nast˛epujac
˛ a˛ kwesti˛e:
P ROBLEM 2. Jakie artefakty sa˛ zazwyczaj dost˛epne w projektach programistycznych?
Bez wzgl˛edu na metodyk˛e używana˛ w projekcie, nast˛epujace
˛ informacje zdaja˛ si˛e
być używane dość cz˛esto [12, 16, 38, 41]:
• Uzasadnienie Biznesowe—prezentuje uzasadnienie dla prowadzenia prac.
• Specyfikacja Wymagań Oprogramowania—opisuje oprogramowanie, które ma
zostać stworzone.
• Testy Akceptacji—zapewniaja,
˛ że oprogramowanie spełnia wymagania klienta
[19, 32].
4.4 Generowanie instrukcji obsługi
W celu wygenerowania instrukcji obsługi należy rozpatrzeć również nast˛epujac
˛ a˛
kwesti˛e:
4.4. Generowanie instrukcji obsługi
19
P ROBLEM 3. Jakiego rodzaju dane sa˛ wymagane aby wygenerować instrukcj˛e obsługi
i gdzie można te dane znaleźć?
W celu skupienia prac badawczych na generowaniu instrukcji obsługi postanowiono postawić nast˛epujace
˛ założenia dotyczace
˛ artefaktów:
Z AŁO ŻENIE 1. Nast˛epujace
˛ artefakty sa˛ dost˛epne: 1) Uzasadnienie biznesowe, 2)
Specyfikacja wymagań, 3) Testy Akceptacyjne, oraz 4) interaktywne makiety lub działajaca
˛ aplikacja.
Artefakty moga˛ si˛e różnić pomi˛edzy firmami i metodykami (np. ze wzgl˛edu na
ich dopasowanie do warunków i zwyczajów panujacych
˛
w firmie), stad
˛ też ważne jest
by określić ich zawartość:
Z AŁO ŻENIE 2. Wymagania funkcjonalne sa˛ zdefiniowane w postacji przypadków
użycia [7] przy pomocy Formal USE Cases notation (FUSE) [27].
U ZASADNIENIE . Wymagania funkcjonalne moga˛ być przedstawione w wielu formach,
np. jako przypadki użycia lub historyjki [1, 8, 23]. Oba zapisy używaja˛ j˛ezyka naturalnego (co pozwala opisać funkcjonalność w łatwy do zrozumienia sposób), jednakże
przypadki użycia zdaja˛ si˛e być lepiej dostosowane do analizy automatycznej [31].
FUSE pozwala na zorganizowanie struktury przypadków użycia.
Z AŁO ŻENIE 3. Testy akceptacyjne definiuje si˛e używajac
˛ Test Description Language
(TDL) [32], a makiety ekranów definiuje si˛e przy użyciu ScreenSpeca [33].
U ZASADNIENIE . ScreenSpec pozwala na zdefiniowanie szkiców ekranów, które można
zwizualizować i umieścić w instrukcji obsługi. Gdy aplikacja jest już dost˛epna szkice
można zastapić
˛
zrzutem ekranu pochodzacym
˛
z rzeczywistej aplikacji. Z testów
akceptacyjnych można pobrać przykładowe dane. Ponadto, TDL łaczy
˛
przypadki
testowe z przypadkami użycia, a to pozwala zobaczyć za co odpowiedzialny jest dany
przypadek testowy.
Z AŁO ŻENIE 4. Wymagania pozafunkcjonalne (NFRs) sa˛ zdefiniowane przy pomocy
Non-functional Requirement Templates (NoRTs) [25], a ograniczenia techniczne przy
pomocy Technical Constraint Templates (TeCTs).
U ZASADNIENIE . Używanie katalogu NoRTs do zdefiniowania NFRs pozwala zwi˛ekszyć
jakość artefaktów. TeCTs używaja˛ takiego samego podejścia.
Aby skupić si˛e na celu przedstawionym w Rozdziale 4.1, założono także:
Z AŁO ŻENIE 5. Wszystkie artefakty sa˛ aktualne oraz sa˛ napisane zgodnie z popularnymi rekomendacjami.
4.5. Naiwna instrukcja obsługi
20
U ZASADNIENIE . Celem pracy jest wygenerowanie instrukcji obsługi, a nie analizowanie jakości informacji zawartych w artefaktach.
Dane z artefaktów użyte sa˛ do konstrukcji bazy danych. Specyficznym rodzajem danych sa˛ szablony, które to organizuja˛ struktur˛e instrukcji obsługi poprzez
zdefiniowanie gdzie należy umieścić dany komponent i co ma si˛e w nim znajdować.
4.5 Naiwna instrukcja obsługi
W tym podejściu informacje dost˛epne w artefaktach kopiowane sa˛ do instrukcji
obsługi bez przetworzenia. Wydaje si˛e naiwnym opierać wyjaśnienia aplikacji głównie
na scenariuszach z przypadków użycia, zwłaszcza że dobrze napisane przypadki nie
maja˛ ani odniesienia do komponentów GUI, ani przykładowych danych. Ta obawa
została potwierdzona w trakcie wst˛epnej oceny.
4.6 Wymagania dotyczace
˛ środowiska pracy
Na podstawie uwag uczestników wst˛epnego eksperymentu (Rozdział 4.5) postanowiono zadać (m.in.) dodatkowe pytania:
P ROBLEM 4. Gdzie można znaleźć adres strony internetowej?
P ROBLEM 5. Gdzie można uzyskać wymagania dotyczace
˛ komputerów użytkowników i informacje na temat ich wykształcenia (wiedza, umiej˛etności, itd)?
Aby podołać tym kwestiom, postanowiono skorzystać z informacji zawartych
w wymaganiach pozafunkcjonalnych i ograniczeniach technicznych. Wymagania
te cz˛esto sa˛ definiowane w j˛ezyku naturalnym, a użycie katalogu Non-Functional
Requirements Templates wraz z Technical Constraint Templates pozwala na łatwe
pozyskanie wymaganych informacji [25].
4.7 Przykłady użycia
Według wst˛epnych badań (patrz Rozdział 4.5) opis zadań powinien być wzbogacony
o przykłady pokazujace
˛ jak osiagn
˛ ać
˛ wymagany cel przy użyciu aplikacji. Według
uczestników badań, dobrym sposobem na to byłaby prezentacja interakcji pomi˛edzy
użytkownikiem a systemem używajac
˛ zrzutów ekranu oraz rzeczywistych danych.
Niniejszy rozdział skupia si˛e na tej kwestii:
21
4.8. Wst˛epna ocena
P ROBLEM 6. Jak można wygenerować opisy prezentujace
˛ interakcj˛e pomi˛edzy użytkownikiem a systemem używajac
˛ zrzutów ekranu, przykładowych danych oraz opisu
słownego?
Testy akceptacyjne zawieraja˛ przykładowe dane (które moga˛ zostać użyte do
uruchomienia aplikacji, aby zebrać zrzuty ekranu), a przypadki użycia opisuja˛ zamierzenia stojace
˛ za czynami użytkownika. Używajac
˛ tych danych można wygenerować
opis prezentujacy
˛ jak użyć aplikacji.
Proces tworzenia przykładów przebiega nast˛epujaco:
˛
1. Analiza zależności (w danych)
2. Wybór przypadków testowych (które posłuża˛ do generowania opisów)
3. Planowanie opisu
4. Analiza aktywności w przypadkach użycia [30, 31]
5. Generowanie opisów
Rysunek 4.1 przedstawia przykładowa˛ reguł˛e generowania, a Rysunek 4.2 jej
wynik.
4.8 Wst˛epna ocena
W celu wyeliminowania potencjalnych słabości przeprowadzono wst˛epna˛ ocen˛e
zaproponowanych metod1 , opracowano prototyp, wygenerowano instrukcj˛e obsługi
oraz przeprowadzono ocen˛e eksperymentalna.
˛
1 Naiwna instrukcja obsługi została oceniona podczas innej oceny
User < SELECT > [ CLICK ] {
The browser should look like this :
{{ $1 . tests [0]. screen [" pre "]| screen }}
Select {{ $1 . ucstep . matter }} by clicking
{{ $1 . tests [0]. component . screen [" pre "]| screen ( ’ inline ’) }}.
}
Rysunek 4.1: Prosta reguła generowania treści
The browser should look like this :
<img >
Select system main page by clicking OPEN .
Rysunek 4.2: Wynik reguły generowania z Rysunku 4.1 (zrzut ekranu został zastapiony
˛
etykieta˛ <img> dla zaoszcz˛edzenia miejsca)
4.9. Wnioski
22
4.8.1 Badania wst˛epne
Badanie zostało przeprowadzone w dwóch etapach. Na poczatku
˛
pierwszego etapu
przygotowano trzy warianty nast˛epujacych
˛
komponentów: Wprowadzenie, Wymagania dotyczace
˛ środowiska pracy, Obiekty informacyjne, oraz Zadania. Nast˛epnie zorganizowano spotkania na których omówiono propozycje. Odbyły si˛e cztery spotkania,
na które zaproszono dwóch programistów (osoby z komercyjnym doświadczeniem)
oraz dwóch laików komputerowych.
Po przeprowadzeniu wszystkich spotkań zaprojektowano nowa˛ wersj˛e każdego z
komponentów i przystapiono
˛
do drugiego etapu. Tym razem zaprezentowano jeden
wariant każdego z komponentów i poproszono uczestników o jego ulepszenie.
4.8.2 Ocena empiryczna
Instrukcja obsługi dla aplikacji Plagiat.pl [35] została wygenerowana i oceniona za
pomoca˛ modelu jakości COCA oraz metody DET [4]. Plagiat.pl jest aplikacja˛ pozwalajac
˛ a˛ na wykrycie plagiatu w różnego rodzaju dokumentach, np. w pracach
magisterskich.
Tuż przed wygenerowaniem instrukcji stworzono wymagane artefakty na podstawie naszego doświadczenia z aplikacja˛ Plagiat.pl.
Wygenerowana instrukcja obsługi została oceniona przez 3 Ekspertów i 16 potencjalnych użytkowników2 . Eksperyment został przeprowadzony zgodnie z procedura˛
zaproponowana˛ przez Alchimowicza i Nawrockiego [4].
Wyniki eksperymentu przedstawiono w Tabelach 4.3 i 4.4. Odpowiedzi dostarczone przez Ekspertów sa˛ zbliżone do odpowiedzi z eksperymentu przeprowadzonego w ramach prac nad modelem jakości COCA. W przypadku metody DET, potencjalni użytkownicy byli w stanie znaleźć 85.13% poprawnych odpowiedzi, co było
lepszym wynikiem niż wersja podstawowa oraz profil jakości (odpowiednio 2.16% i
4.09%).
4.9 Wnioski
Celem pracy było zbadanie możliwości wygenerowania instrukcji obsługi o jakości nie
gorszej niż materiały opracowane przez człowieka. Praca opisuje wst˛epne badania.
Założono, że wygenerowanie instrukcji obsługi opiera si˛e na uzasadnieniu biznesowym, specyfikacji wymagań, testach akceptacyjnych oraz na działajacej
˛ aplikacji (czy
też makietach). Założono również, że specyfikacja wymagań zawiera wymagania
funkcjonalne i poza-funkcjonalne, a także ograniczenia techniczne.
2 Wszyscy zadeklarowali brak znajomości aplikacji.
23
4.9. Wnioski
Tablica 4.3: Ocena jakości instrukcji obsługi dla Plagiat.pl (model jakości COCA).
Id Charakterystyka
Profil
wraz z pytaniem
–
?
+
Kompletność
Q1 W jakim stopniu dokumentacja 22.22% 29.63% 48.15%
użytkownika pokrywa cała˛ funkcjonalność systemu z wymaganym poziomem szczegółowości?
Q2 W jakim stopniu dokumentacja 3.70% 11.11% 85.19%
użytkownika dostarcza informacje pomocne w podj˛eciu decyzji czy system odpowiada potrzebom potencjalnych użytkowników?
Q3 W jakim stopniu dokumentacja
użytkownika zawiera informacje
jak z niej korzystać w sposób
skuteczny i efektywny?
Operowalność
Q4 W jakim stopniu dokumentacja
użytkownika jest łatwa w użyciu
i pomocna podczas obsługi systemu udokumentowanego przez
nia?
˛
Poprawność
Q5 W jakim stopniu dokumentacja użytkownika dostarcza poprawne opisy z wymaganym poziomem szczegółowości?
Wyglad
˛
Q6 W jakim stopniu informacje zawarte w dokumentacji użytkownika prezentowane sa˛ w sposób
estetyczny?
15.60%
R˛ecznie napisana
–
?
+
0.00% 33.33%
0.00%
7.40% 77.00% 25.00%
Wygenerowana
–
?
+
odpowiedzialny: Ekspert
66.67% 0.00% 33.33% 66.67%
0.00% 100.00%
0.00%
0.00% 100.00%
odpowiedzialny: Potencjalny użytkownik
6.25% 68.75% 12.50% 12.50% 75.00%
odpowiedzialny: Potencjalny użytkownik
8.20% 14.90% 77.10% 31.25% 12.50% 56.25% 0.00% 25.00% 75.00%
18.52% 25.93% 55.56%
0.00% 33.33%
66.67%
odpowiedzialny: Ekspert
0.00% 33.33% 66.67%
odpowiedzialny: Potencjalny użytkownik
13.60% 12.20% 74.30% 31.25% 12.50% 56.25% 12.50% 6.25% 81.25%
Tablica 4.4: Porównanie operowalności instrukcji obsługi do aplikacji Plagiat.pl (metoda DET).
Profil
Liczba uczestników
Średni czas wyszukiwania odpowiedzi
Procent poprawnych odpowiedzi
148
49 min
81.04%
Wariant
R˛ecznie napisana
Wygenerowana
16
16
39 min
42 min
82.97%
85.13%
4.9. Wnioski
24
Struktura wygenerowanej instrukcji obsługi opiera si˛e na analizie literatury. Zaproponowano dwa warianty instrukcji obsługi:
• naiwna—która˛ można stworzyć na podstawie informacji zawartych w artefaktach, oraz
• kompletna–która wymaga istniejacych
˛
oraz wygenerowanych elementów (opcja
ta jest zgodna ze standardem ISO 26514:2008 [17] i rekomendacjami Sun Technical Publications [40]).
Instrukcja obsługi dla komercyjnej aplikacji Plagiat.pl została wygenerowania
i oceniona w kontrolowanym eksperymencie przy użyciu modelu jakości COCA oraz
metody DET. Wyniki pokazuja,
˛ że jakość wygenerowanej instrukcji jest nie gorsza
od tej sporzadzonej
˛
przez ludzi. Aby sprawdzić jakość wygenerowanej instrukcji w
innych przypadkach potrzebne sa˛ dodatkowe badania.
Rozdział 5
Podsumowanie
Celem pracy było zbadanie możliwości generowania dokumentacji użytkownika (zawierajacej
˛
instrukcj˛e obsługi wraz z objaśnieniami pól), której jakość nie ust˛epowałaby materiałom opracowanym przez człowieka. Wyniki badań potwierdzaja,
˛ że
istnieje możliwość wygenerowania instrukcji obsługi dla aplikacji internetowych o
jakości nie gorszej niż materiały stworzone przez człowieka.
Z badań można wyciagn
˛ ać
˛ nast˛epujace
˛ wnioski:
W NIOSEK 1. Jakość komercyjnych instrukcji nie jest zbyt wysoka.
Komentarz 1. Żadna z komercyjnych instrukcji użytych do stworzenia profilu jakościowego COCA nie otrzymała 100% odpowiedzi “bardzo dobrych” na którekolwiek z
zadanych pytań (Rozdział 2). 29% uczestników eksperymentu udzieliło odpowiedzi
“bardzo dobre” na pytanie Q4 i była to najwyższa ocena ze wszystkich. Co wi˛ecej, tylko
55% uczestników eksperymentu dało odpowiedź “wystarczajaco”
˛ pytaniu Q2. W przypadku zsumowania odpowiedzi “wystarczajaco”
˛ i “bardzo dobre” najwyżej ocenionym
pytaniem jest Q2 - 85% pozytywnych odpowiedzi. Podczas omawiania metody DET
procent poprawnych odpowiedzi mieścił si˛e pomi˛edzy 77% a 87%, a średnia wartość
wynosiła około 81%.
W NIOSEK 2. Korzystajac
˛ z wyrażeń regularnych możliwe jest stworzenie 3-cz˛eściowego
opisu pola (zawierajacego
˛
opis słowny, diagramy oraz zestaw przykładów), którego
jakość jest nie gorsza od odpowiedników napisanych przez człowieka.
Komentarz 2. Opracowano szereg metod, które pozwalaja˛ na analiz˛e wyrażeń regularnych i stworzenie na ich podstawie łatwych do zrozumienia objaśnień. Zaproponowane metody zostały eksperymentalnie ocenione poprzez sprawdzenie 5 przykładowych
pól używanych w aplikacjach internetowych. W przeprowadzonym eksperymencie
25
Podsumowanie
26
objaśniania pól stworzone przez prototypowe narz˛edzie otrzymało 84% poprawnych
odpowiedzi, podczas gdy objaśnienia napisane przez człowieka 77-78%.
W NIOSEK 3. Możliwym jest wygenerowanie dobrej jakości instrukcji obsługi na podstawie uzasadnienia biznesowego, specyfikacji wymagań (zawierajacej
˛ przypadki użycia), testów akceptacyjnych oraz działajacego
˛
oprogramowania (badź
˛ makiety GUI).
Komentarz 3. Badania, oparte na systemie komercyjnym Plagiat.pl i opracowanym
zestawie metod generowania (Rozdział 4) pokazuja,
˛ że wygenerowana instrukcja nie
ust˛epuje jakościa˛ jej komercyjnemu odpowiednikowi. Wygenerowana instrukcja była
nie gorsza w przypadku wszystkich charakterystyk jakości dla modelu jakości COCA.
Metoda DET także potwierdziła, że wygenerowane instrukcje obsługi sa˛ nie gorsze od
tych napisanych przez człowieka: procent poprawnych odpowiedzi dla wersji wygenerowanej wynosił 85%, podczas gdy dla stworzonej przez człowieka 83%.
W NIOSEK 4. Dokumenty dobrej jakości (takie jak uzasadnienie biznesowe, przypadki
użycia, skrypty do testów akceptacyjnych) moga˛ być użyte do automatycznego generowania instrukcji obsługi, co pozwala na zmniejszenie kosztów produkcji .
Komentarz 4. Zastosowanie wygenerowanej instrukcji obsługi nie jest ograniczone do
celów edukacyjnych. Berry i inni stwierdzili, że instrukcja obsługi może być użyta jako
wymagania dla tworzonego oprogramowania [5]. Tak wi˛ec, wygenerowana instrukcja
obsługi może być użyta jako dodatkowy artefakt użyty do zapewnienia jakości.
Bibliografia
[1]
Steve Adolph and Paul Bramble. Patterns for Effective Use Cases. Addison Wesley, Boston, 2002.
ISBN 978-0201721843.
[2]
Alfred V. Aho, Monica S. Lam, Ravi Sethi, and Jeffrey D. Ullman. Compilers: Principles, Techniques,
and Tools. Addison-Wesley Longman Publishing Co., Inc., Boston, MA, USA, 2nd edition, 2006.
ISBN 0321486811.
[3]
Bartosz Alchimowicz and Jerzy Nawrocki. Generating syntax diagrams from regular expressions.
Foundations of Computing and Decision Sciences, 36(2):81–97, 2011.
[4]
Bartosz Alchimowicz and Jerzy Nawrocki. The COCA quality model for user documentation.
Software Quality Journal (not assigned to an issue yet), 2014.
[5]
Daniel M Berry, Khuzaima Daudjee, Jing Dong, Igor Fainchtein, Maria Augusta Nelson, Torsten
Nelson, and Lihua Ou. User’s manual as a requirements specification: case studies. Requirements
Engineering, 9(1):67–82, 2004.
[6]
IEEE-SA Standards Board. IEEE Std 1063-2001, IEEE standard for Software User Documentation.
Institute of Electrical and Electronics Engineers, 2001.
[7]
Alistair Cockburn. Writing Effective Use Cases. Addison-Wesley Longman Publishing Co., Inc.,
Boston, MA, USA, 1st edition, 2000. ISBN 0201702258.
[8]
Mike Cohn. User stories applied: For agile software development. Addison-Wesley Professional,
2004.
[9]
Microsoft Corporation. Microsoft Manual of Style. Microsoft Press Series. Microsoft Press, 4th
edition, 2012. ISBN 9780735648715.
[10] F. DeRespinis, J. Jenkins, International Business Machines Corporation, A. Laird, P. Hayward, and
L.I. McDonald. The IBM Style Guide: Conventions for Writers and Editors. IBM Press Series. IBM
Press/Pearson, 2011. ISBN 9780132101301.
[11] Julie Fisher. User Satisfaction and System Success: considering the development team. Australasian
Journal of Information Systems, 9(1):21–29, 2001. ISSN 1449-8618.
[12] Karl Fogel. Producing open source software: How to run a successful free software project. O’Reilly
Media, Inc., 2005.
[13] Richard Hazlett. Measurement of user frustration: a biologic approach. In CHI ’03 Extended
Abstracts on Human Factors in Computing Systems, CHI EA ’03, pages 734–735, New York, NY, USA,
2003. ACM. ISBN 1-58113-637-4. doi: 10.1145/765891.765958.
[14] ISO/IEC. ISO/IEC 14977:1996 - Information technology – Syntactic metalanguage – Extended BNF.
International Organization for Standardization, Geneva, Switzerland, 1996.
27
28
[15] ISO/IEC. ISO/IEC 25000:2005 - Software engineering – Software product Quality Requirements and
Evaluation (SQuaRE) – Guide to SQuaRE. International Organization for Standardization, Geneva,
Switzerland, 2005.
[16] ISO/IEC. ISO/IEC 12207:2008 - Systems and software engineering – Software life cycle processes.
International Organization for Standardization, Geneva, Switzerland, 2008.
[17] ISO/IEC. ISO/IEC 26514:2008 - Systems and software engineering – Requirements for designers
and developers of user documentation. International Organization for Standardization, Geneva,
Switzerland, 2008.
[18] ISO/IEC. ISO/IEC 26513:2009 - Systems and software engineering – Requirements for testers and
reviewers of user documentation. International Organization for Standardization, Geneva, Switzerland, 2009.
[19] ISO/IEC/IEEE. ISO/IEC/IEEE 24765:2010 - Systems and software engineering – Vocabulary. International Organization for Standardization, Geneva, Switzerland, 2010.
[20] ISO/IEC/IEEE. ISO/IEC 26512:2011 - Systems and software engineering – Requirements for acquirers
and suppliers of user documentation. International Organization for Standardization, Geneva,
Switzerland, 2011.
[21] ISO/IEC/IEEE. ISO/IEC 26511:2012 - Systems and software engineering – Requirements for managers
of user documentation. International Organization for Standardization, Geneva, Switzerland, 2012.
[22] ISO/IEC/IEEE. ISO/IEC 26515:2012 - Systems and software engineering – Developing user documentation in an agile environment. International Organization for Standardization, Geneva,
Switzerland, 2012.
[23] Ivar Jacobson. Concepts for Modeling Large Real Time Systems. Royal Institute of Technology,
Department of Telecommunication Systems-Computer Systems, 1985.
[24] T. Capers Jones. Estimating Software Costs: Bringing Realism to Estimating. McGraw-Hill, Inc.,
New York, NY, USA, 2nd edition, 2007. ISBN 9780071483001.
[25] S. Kopczynska and J. Nawrocki. Using non-functional requirements templates for elicitation: A
case study. In Requirements Patterns (RePa), 2014 IEEE 4th International Workshop on, pages
47–54, Aug 2014.
[26] Mike Markel. Technical Communication. Bedford/St. Martin’s, 2012. ISBN 9780312679484.
[27] Jerzy R. Nawrocki and Łukasz Olek. Use-Cases Engineering with UC Workbench. In Krzysztof
Zielinski and Tomasz Szmuc, editors, Software Engineering: Evolution and Emerging Technologies,
volume 130 of Frontiers in Artificial Intelligence and Applications, pages 319–329. IOS Press, 2005.
ISBN 978-1-58603-559-4.
[28] David G. Novick and Karen Ward. What users say they want in documentation. In Shihong Huang,
Rob Pierce, and John W. Stamey Jr., editors, SIGDOC, pages 84–91. ACM, 2006. ISBN 1-59593-523-1.
[29] David G. Novick and Karen Ward. Why don’t people read the manual? In Shihong Huang, Rob
Pierce, and John W. Stamey Jr., editors, SIGDOC, pages 11–18. ACM, 2006. ISBN 1-59593-523-1.
[30] Mirosław Ochodek and Jerzy Nawrocki. Automatic Transactions Identification in Use Cases. In
Balancing Agility and Formalism in Software Engineering: 2nd IFIP Central and East European
Conference on Software Engineering Techniques CEE-SET 2007, volume 5082 of LNCS, pages 55–68.
Springer Verlag, 2008.
[31] Mirosław Ochodek, Bartosz Alchimowicz, Jakub Jurkiewicz, and Jerzy Nawrocki. Improving the
reliability of transaction identification in use cases. Information and Software Technology, 53(8):
885–897, 2011.
29
[32] Łukasz Olek, Bartosz Alchimowicz, and Jerzy Nawrocki. Acceptance testing of web applications
with test description language. Computer Science, 15(4):459–477, 2014.
[33] Łukasz Olek, Jerzy Nawrocki, and Miroslaw Ochodek. Enhancing Use Cases with Screen Designs.
In Zbigniew Huzar, Radek Kocí, Bertrand Meyer, Bartosz Walter, and Jaroslav Zendulka, editors,
CEE-SET, volume 4980 of Lecture Notes in Computer Science, pages 48–61. Springer, 2008. ISBN
978-3-642-22385-3.
[34] Arancha Pedraz-Delhaes, Muhammad Aljukhadar, and Sylvain Sénécal. The effects of document
language quality on consumer perceptions and intentions. Canadian Journal of Administrative
Sciences/Revue Canadienne des Sciences de l’Administration, 27(4):363–375, 2010.
[35] Plagiat.pl. Instrukcja Użytkownika Internetowego Systemu Antyplagiatowego Plagiat.pl. Plagiat.pl Sp. z o.o., 2012. URL https://www.plagiat.pl/cms_pdf/Plagiat_pl_instrukcja_
uzytkownika_indywidualnego.pdf. [Online; accessed 2 July 2014].
[36] Ehud Reiter, Chris Mellish, and Jon Levine. Automatic Generation of Technical Documentation.
Journal of Applied Artificial Intelligence, 9(3):259–287, 1995.
[37] Marc Rettig. Nobody Reads Documentation. Communications of the ACM, 34(7):19–24, July 1991.
[38] Ken Schwaber. Agile project management with Scrum. Microsoft Press, 2004.
[39] Cathy J. Spencer. A Good User’s Guide Means Fewer Support Calls and Lower Support Costs.
Technical Communication, 42(1):52–55(4), February 1995.
[40] Sun Technical Publications. Read Me First!: A Style Guide for the Computer Industry. Prentice Hall,
3rd edition, 2010. ISBN 9780137058266.
[41] TSO. Managing successful projects with PRINCE2. HM Government – Best management practice.
Stationery Office, 2009. ISBN 9780113310593.
[42] Pierre Wellner, Mike Flynn, Simon Tucker, and Steve Whittaker. A Meeting Browser Evaluation Test.
In CHI ’92: Proceedings of the SIGCHI Conference on Human Factors in Computing Systems, New
York, NY, USA, 0 2005. ACM Press. ISBN 1-59593-002-7.