\chapter{Case study}
\markboth{Case study}{}

As mentioned in Section 1.2.1, one goal of this thesis is for it to be a case 
study in the use of a user's manual of a software product as the product's 
requirements specification. The goal of the case study is to see how well the 
user's manual of \program{WD-pic} works as the requirement specification and 
how effectively the manual can be used as a reference in the design, 
implementation and testing phases. In this case study, Berry worked as the 
customer of \program{WD-pic}. The author of this thesis was the software 
designer, developer and tester. 

\section{Project plan}
\markright{Project plan}

The project started in the beginning of October, 2001. It was planned to 
be finished by the end of July, 2002, for a total duration of 10 months. 
The project schedule was planned as a classic waterfall, as illustrated in 
Figure~\ref{fig:plan}. The rest of this section quotes the project plan as it 
was written in September, 2001, including the project schedule, requirements, 
design, implementation, and testing plans. 

\begin{figure}
\begin{center}
\scalebox{0.7}[0.7]{\includegraphics{plan.ps}}
\end{center}
\caption{\program{WD-pic} project plan}\label{fig:plan}
\end{figure}

\begin{quotation}
\subsubsection{Schedule}
\begin{itemize}
\item preparation 1 month, from October 1 to October 31, 2001  
\item requirement 2 months, from November 1 to December 31, 2001
\item design 1 month, from January 1 to January 31, 2002
\item implementation 3 months, from February 1 to April 31, 2002
\item testing 2 months, from May 1 to June 31, 2002
\item others 1 month
\end{itemize}
During the whole development process, the manual will be kept up to date.

The preparation phase is to study Shpilberg's prototype of \program{WD-pic} 
and all the existing documents, and to get familiar with \program{pic}, its 
features, its source code, \program{Java Swing}, and \program{Jni}. 

One month flexible time is left to deal with unexpected events.
 
\subsubsection{Requirements}

No formal requirements specification will be written. Instead we will start by 
writing a user's manual, which will be used as the requirements specification. 
The software engineer will discuss with the customer all the features and 
document them in the manual. The user's manual will be organized by use cases. 
It will describe all the fundamental concepts as well and is not to be 
ambiguous.

\subsubsection{Design}

All the features in the manual will be designed. High-level design modules 
should be given. The design should be clear enough to show how the modules 
work together. 

\subsubsection{Implementation}

All the features in the manual will be implemented. \program{Java Swing} will 
be used to code the GUI. \program{Java Jni} will be used to communicate 
between the \program{Java} coded GUI and the \program{C} coded \program{pic} 
compiler.

The project will be carried out on a \program{Unix Solaris} environment.

\subsubsection{Testing}

Both black-box testing and white-box testing will be used to test the program. 
The user's manual will be used as a source of test cases for black-box 
testing. All the use cases in the manual should be covered. 

Unit-testing will be done on every class.

\end{quotation}

\section{Results and introspection}
\markright{Results and introspection}

The project was carried out, not exactly matching the schedule that was 
planned. The following is a list of the actual milestones:

\begin{itemize}
\item October 2, 2001, project started
\item November 1, manual started 
\item March 28, 2002, manual final (design started)
\item April 20, design final (implementation started)
\item April 22, manual first update 
\item May 15, first demo (basic features done)
\item May 16, manual second update
\item June 11, second demo (all features done)
\item July 31, testing end
\end{itemize}

Figure~\ref{fig:process} illustrates the whole development process.
\begin{figure}
\begin{center}
\scalebox{0.7}[0.7]{\includegraphics{process.ps}}
\end{center}
\caption{\program{WD-pic} development process}\label{fig:process}
\end{figure}

Some phases in the software development process are not exactly bounded to the 
clear timeline. The spare time in the previous phases of implementation was 
used to do research, such as writing proof of concept (POC) code. The 
implementation phase was counted from writing the main frame code of 
\program{WD-pic}.

White-box testing was actually combined with the implementation phase. 
Whenever a class was developed, it was white-box tested. Whenever a feature 
was implemented, it was tested against the use case in the manual. Thus, the 
testing phase in Figure~\ref{fig:process} was for only black-box testing after 
all the features were implemented, \ie\ integration testing and system testing.
 
\subsection{Requirements}
The requirement phase took longer time than that was planned, totaling 4 
months, from writing the outline to finishing up all the features. Writing the 
manual was actually the process of requirements elicitation. Sometimes, a 
feature was proposed in a very early version, but it took several revisions to 
capture what the customer really wanted. In some cases, the customer did not 
know exactly what he wanted until he had seen the manual description of what 
he thought he wanted. We had 11 revisions before the implementation started, 
and 3 more revisions later when the author decided to change the manual from 
\program{MS Word} format to \LaTeX\ format. Some revisions had only minor 
changes, to correct mostly grammar mistakes.

To avoid ambiguity, the final version of \program{WD-pic} user's manual has a 
glossary defining 34 fundamental concepts including the program name 
``WD-pic'', ``user'', ``grid'', and ``gravity''. The main part of the manual 
was organized by use cases, from basic use cases to advanced features. A 
step-by-step sample run was given for each use case.
 
Later, after implementation started, we had the following several updates. 
\begin{itemize}
\item We planed to play an alert sound if there was a syntax error when the 
user tying in the edit window. We decided to use a different color, red, to 
mark out the text with errors, as this would help the user better than the 
sound, which is unfocused. 

\item A status bar was added at the bottom of the main frame to show session 
command errors. The advantage of using status bar is that the user does not 
have to click the \wid{OK} button in the warning dialog as in other 
applications. The coordinates of the cursor on the canvas can always be shown 
in the status bar as well. 

\item A selected object is highlighted in the same color as the selected text 
in the edit window. Then the user can easily see the relationship between the 
selected object on the canvas and the selected object in the edit window.
 
\item The manual said that when the user selected an object on the canvas, the 
attributes of that object would be shown in the attribute area. However, in 
the implementation, the attribute area is made up of attribute buttons. It 
proved difficult to show all the values of the attributes in the attribute 
area. So, we changed the attribute buttons to be used for insertion only, \ie\ 
no matter what the existing values are, LMCing an attribute button always 
resets the value of the attribute in the internal representation to the value 
in the field next to the attribute button. 

\item There is no grid information in the internal representation, but the 
customer wants grids to be saved. Therefore, we need to save the grids in 
a 
file on 
the hard disk. During the implementation, we realized that we can use this 
file also to create a recently opened file history, which is a popular feature 
in most GUI applications.

\item The manual said that preference setting affected input from the palette 
the same as it affected to input from the keyboard. In the implementation, it 
is difficult to let the program know that a given token is input from the 
keyboard. So we changed the preference setting to affect only the input from 
the palette. Refer to the user's manual for details.   

\item We planned to develop and execute \program{WD-pic} in only a 
\program{Unix} environment. Because the code was written in \program{Java}, we 
built a \program{Windows} version without too many changes in the code.
\end{itemize}
The first three updates could have been avoided if we had done a better review 
of the  manual. However, the last four were unavoidable since they are related 
to implementation details.

Compared to writing traditional requirements specification, writing the user's 
manual at the requirement phase has the following advantages.
\begin{itemize}
\item The user's manual is written at the user's level, so it is easy for the 
user or the customer to see and to tell what he or she wants. It helps 
requirements elicitation. 
\item It is also easier for the software engineer to capture what the customer 
wants. By writing a use-cases-centered user's manual, what the user inputs to 
the CBS and how the CBS responds to the user are clear to the software 
engineer. 
\item By reading the use cases, the customer can verify whether these are what 
he or she wants. 
\end{itemize}

Berry's past experiences being a requirement engineer and being a software 
customer is relevant to this case study, because he learned how to be a 
demanding customer. His previous experience with \program{WD-pic} was 
irrelevant, because each time he played customer, he demanded what he believed 
at the time to be good requirements. The fact that he has been a customer for  
\program{WD-pic} before changes only the set of features required, and not the 
software engineer's job to find out what he wants and to specify and implement 
it. 
 
\subsection{Design}
\program{WD-pic} user's manual was used as the guideline for design. It is 
actually a repository of use cases, from basic to advanced. By reading all the 
use cases, it is not difficult for the designer to figure out the main 
modules. Then each key use case was visualized to a \program{UML} sequence 
diagram. Last, the user's manual was used to verify whether the designed 
modules working together to carry out all the use cases. Some of these 
sequence diagrams are given in Appendix B.

The user's manual helps the design in the following ways.
\begin{itemize}
\item The use cases are already provided. Therefore, it is easy for the 
designer to generate the use-case diagrams.

\item Because a use case in the manual describes in each step what the user 
inputs to the CBS or what the CBS responds to the user, it is easy for the 
designer to construct the sequence diagrams for the scenarios.
  
\item The manual helps the designer to verify whether the design covers all 
the features in the manual. He or she must trace each use case through the 
design.
\end{itemize}  

\subsection{Implementation}
The user's manual was used as the guideline to implement all the features. 
Lots of research was done during the process of preparation and requirement, 
such as studying the \program{pic} source code and Shpilberg's prototype code 
and getting familiar with \program{Java Swing} and \program{Jni}. POC code was 
written in the requirement and design phases. For instance, a small piece of 
\program{Java} code was written to show that the \program{C}-coded 
\program{pic} compiler works with a simple \program{Java}-coded GUI program. 
Therefore, once the design was fixed, the software engineer could write a main 
frame and put everything together to make a rough working version, then 
implement the use cases and abstracted features in the manual one by one. From 
this rough working version to all features done, it took about two months. 
Totally, there are 24,091 lines of code (LOCs) in \program{WD-pic}. Among all 
the source code, 13,524 LOCs are GUI code in \program{Java}, 10,464 LOCs are 
\program{pic} compiler code in \program{C}, and 103 LOCs are external editor 
code in \program{C}. Among the \program{pic} compiler code, 9,567 LOCs are 
reused code from the original \program{pic} compiler. 897 LOCs are newly 
coded. Implementation went much faster than expected.    

\program{WD-pic} was planned to run only on \program{Unix Solaris} systems. 
However, the result shows that after compiling the \program{pic} source code 
into a dynamic link library on \program{Windows},  it works with the GUI in 
\program{Java} on \program{Windows} as well. So a \program{Windows} version of 
\program{WD-pic} was implemented as well, with slightly different code for 
font setting and invoking the external editor.
 
\subsection{Testing}
White-box, unit testing was done to every class during the implementation 
phase. The user's manual was used as the test plan and the source of black-box 
test cases. Results show that the user's manual works as a good test plan and 
source of test cases. The user's manual has all the information that a normal 
test plan and test cases have, including the system requirement of the 
program, the execution steps, and the correct results. Once a feature was 
implemented, the software engineer did black-box testing by following the 
exact steps in the manual to make sure the program worked as expected. 

Most of the testing was done during implementation. Later, more black-box 
testing was done when the author used \program{WD-pic} to draw all the line 
diagrams in this thesis. This author learned that it was very convenient 
and 
fast to use \program{WD-pic} to draw a line diagram if the user had the layout 
of the whole diagram in mind. Users of the traditional batch \program{pic} 
reported the same phenomenon.

To summarize, the user's manual helps testing by serving as the test plan and 
providing test cases.

\section{Author's feelings during the life cycle}
\markright{Author's feelings during the life cycle}

When I first heard the idea of using a program's user's manual as 
its requirement specification, the idea sounded a little bit strange, 
because in a normal life cycle, the user's manual is the last document to be 
written. Furthermore, a user's manual and a requirement specification 
have different readers. They have different foci in their contents.

During the preparation phase, as I was getting to know more about the 
\program{pic} program, I was not sure how much this GUI we were 
going to built on top of \program{pic} could enhance the \program{pic} 
program's functionalities. Even if a user knows the \program{pic} language 
well, the flexibility that the \program{pic} program gives to the user is 
limited because of the limitations of the batch mode program. 

The requirement phase was the hardest phase during the whole life cycle. 
The requirement elicitation was hard. Describing the requirement to 
capture what the customer really wanted was hard too. I felt that 
writing a good user's manual which is to be used as a requirements 
specification is as hard as writing a normal requirement specification. We 
didn't save time during the requirement phase by writing the user's manual 
instead of a requirement specification. In fact, I would say that we lost time.

Everything got paid back in the later design, implementation, and testing 
phases. Having walked through the requirement elicitation process, I knew 
exactly what I was supposed to implement. Testing 
became very easy too, as the use-case-oriented manual itself was a source 
of covering test cases. Implementation went much faster than expected. 
When I did the first demonstration to the customer, the customer 
was really impressed.

When I was using \program{WD-pic} to draw the diagrams in this 
thesis, I realized that this software turned out to be much better than I 
expected. The GUI gives users much more flexibility to draw diagrams than 
the original \program{pic} program. Without too much knowledge of the 
\program{pic} language, I was able to draw all kinds of line drawings easily. 

Compared to projects that I did before, the requirement phase in 
this case study was no easier than that in a normal life cycle. I expected 
that writing a user's manual would have been easier than writing 
a formal requirement specification. However, design, implementation, and 
testing went much better than expected. The project finished on time and with 
the customer's satisfaction. While in my past experience, of about 5 years, 
usually the early requirements and design phases went much more smoothly than 
in this project. However, in the past projects, always requirements and design 
problems were discovered during implementation and testing. In this project, 
there were much fewer problems discovered during implementation and testing, 
allowing them to go very quickly.


 


   


