The relevance of end user documentation for improving usability, learnability and operability of software applications is well known. However, software processes often devote little effort to the production of end user documentation due to budget and time constraints, or leave it not up-to-date as new versions of the application are produced. In particular, in the field of Web applications, due to their quick release time and the rapid evolution, end user documentation is often lacking, or it is incomplete and of poor quality. In this paper a semi-automatic approach for user documentation generation of Web 2.0 applications is presented. The approach exploits dynamic analysis techniques for capturing the user visible behaviour of a web application and, hence, producing end user documentation compliant with known standards and guidelines for software user documentation. A suite of tools support the approach by providing facilities for collecting user session traces associated with use case scenarios offered by the Web application, for abstracting a Navigation Graph of the application, and for generating tutorials and procedure descriptions. The obtained documentation is provided in textual and hypertextual formats. In order to show the feasibility and usefulness of the approach, an example of generating the user documentation for an existing Web application is presented in the paper.

1. Using Dynamic Analysis for
Generating End User
Documentation for Web 2.0
Applications
Domenico Amalfitano
Anna Rita Fasolino
Porfirio Tramontana
Dipartimento di Informatica e Sistemistica
University of Naples Federico II, Italy

2. Motivation
 Web 2.0 Applications have emerged as a new
generation of Web applications offering greater usability
and interactivity than traditional ones.
 Web pages have been transformed in complex GUIs with
synchronous and asynchronous interactions with the user and
with the resources
 End User Documentation needs
 The complexity and the variety of interactivity features provided
by a modern Web 2.0 Applications may often confuse the user,
so end user documentation is needed to improve the usability of
the applications
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 2

3. User documentation definitions
 According to the IEEE 1063 standard:
 Instructional mode
 “Usage mode that is intended to teach the use of software in performing
tasks”
 Reference mode
 “Usage mode that is intended to provide quick access to specific information
for software users who are generally familiar with the software functions”
 Procedure:
 “Ordered series of steps that a user follows to do one or more tasks”
 Step:
 “One element of a procedure. A step contains one or more actions”
 Action:
 Element of a step that a user performs to complete a procedure.
 Tutorial:
 “Instructional procedure in which the user exercises software functions using
sample data supplied with the software or documentation”
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 3

4. Some documentation examples
 Tudu list user documentation (our case study)
 Other examples
 ASSP Web Application
 TravWeb
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 4

5. Web 2.0 applications
 Web 2.0 applications have complex User
Interfaces, with both client side and server
side interactions
 Business criticality is related to their
learnability, operability and usability
 The client side code is usually dynamically
generated
 Static analysis techniques can extract only a
limited set of information
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 5

6. Benefits and effort of a good documentation
 Learnability
 Operability
 Usability
 Effort needed to write documentation
 Effort needed to maintain the
documentation up-to-dated
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 6

7. User documentation generation
 Many tools available for the generation of internal
documentation, usually based on static analysis of the
source code:
 Javadoc
 Doxygen
 Some tools can generate tutorials from dynamic
analysis:
 Smart Tutor
 DocWizards
 JTutor
 EpiDocX
 Is it possible to support and partially automate
the process of generation of end user
documentation for a Web 2.0 application?
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 7

8. Our documentation generation
approach
Use Case RIA
 Supports the automatic generationAnalystsome end user
of Scenarios
documentation items RIA
FSMs
Overall navigation Graph
Dynamic
 Analysis
 Scenario execution tutorials Collected Traces
 End user reference guide Navigational
Edited FSMs Model
 Three steps: Repository Generation
 Web Application Dynamic Analyis User
Generation of the Navigation Graph
Documentation
 Generation
 End User Documentation Generation
Introductory Reference
Manual Tutorials Guide
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 8

9. Web Application Dynamic Analysis
Use Case
Act or
+ Name 1..* 1..* + Name
Use case scenarios of the Web application are navigated
+ Description

and described by the documenter 1..*
With the support of the CReRIA tool
Scenar io
 Ex cept ion Scenar io
+ Name
He has to give a name to any Interface Instance and to
+ Description

1
any Transition Instance 1
Ex ecut ion Tr ace
 The tool suggests the reuse of identical names when it judges
that the interface/transitions are “similar”Previouspreviously 1..*
+ to
encountered and described ones 0..1 2..*
 Different clustering heuristics are availablent er face I nst ance
+ Next I
0..1
Tr ansit ion I nst ance
+ Screenshot
1..*
1..*
I nt er face Class Tr ansit ion Class
+ Name + Name
+ Description + Description
+ Node 1..* + Edge
1..*
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 Nav igat ion Gr aph 9

10. Web Application Dynamic Analysis
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 10

11. Navigation Graph Generation
 Overall and scenario specific
navigation graphs can be obtained
 Automatically with the support of the
CReRIA tool for generation and of
the GVEdit tool for visualization
 Graphs and documentation
information can be furtherly edited
 With the support of CReRIA
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 11

12. A case study
 Tudu Lists
 10 KLOC in
Java/JSP
 Rich Client
Interfaces
 Existing user documentation (http://www.julien-
dubois.com/tudu-lists/user-documentation) is limited
to a list of the 8 main use cases, with 4 screen shots
 Often used as a case study for RIAs reverse
engineering and testing
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 12

13. Process execution metrics
 3 actors
 Generic User, Logged User, Administrator
 23 use cases
 120 scenarios
 120 collected execution traces
 42 Interfaces
 By clustering together 425 Interface Instances
 Clustering suggestions accepted 420 out of 425 times
 138 Transitions
 By clustering together 306 Transition Instances
 Transition clustering accepted 278 out of 306 times
 120 generated graphs
 120 generated tutorials
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 13

14. End User Documentation Generation
 On the basis of the information extracted
and abstracted in the previous phases,
have been automatically generated:
 Overall navigation Graph
 Scenario execution tutorials and graphs
 End user reference guide
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011

15. Overall Navigation Graph
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 15

16. An example of scenario navigation graph
Classic Graph Graph view with Screenshots
View
Clickable
nodes
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 16

17. An example of scenario description
Quick Add
In this scenario a logged user can insert a tudu in a selected list of todos.
Event Sequences
Related Regular Scenarios
Advanced Add
Related Exception Scenarios
Insertion of Wrong Data
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011

18. Scenario Tutorials
 Automatically generated as HTML hypertexts
 They can be included in the Web application itself
 The tutorial template includes:
 Scenario name and description
 Involved Actors
 Use case name
 For each interface/transition composing the scenario
 Interface name and description
 Transition name and description
 Input names and values
 Triggering Event
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011

19. Scenario Tutorial example
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 19

20. Scenario Tutorial example
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 20

21. Scenario Tutorial example
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 21

22. Scenario Tutorial example
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 22

23. Possible extensions
 Customization of presentation styles
 Generation in textual formats
 Choose between different styles
 More detailed documentation
 Use of collected traces in testing and reverse
engineering processes
 Use of collected traces for on-line replaying of tutorials
 Assessment of documentation regression
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 23

24. Conclusions and Future Works
 This paper introduced a process and a tool for
the semi-automatic generation of end user
documentation for Web 2.0 applications via
dynamic analysis
 In future works we plan:
 To increase the features of the tool
 To carry out experiments aiming at the comparison
between documentation manually generated and semi-
automatically generated with the support of the tool
 Quality of the documentation
 Needed effort
Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 24

25. Porfirio Tramontana – WSE 2011 – Williamsburg – 09/30/2011 25