comparison docs/Instructions/Instructions.tex @ 2233:1d221694e959

Instructions update: started 'Quick start' section. Some minor changes.

 
 \usepackage{amssymb}
 \usepackage{cite}
 \usepackage{hyperref}				% Hyperlinks
 \usepackage[nottoc,numbib]{tocbibind}	% 'References' in TOC
+\usepackage{url}
 
 \graphicspath{{img/}}					% Relative path where the images are stored. 
 
 \title{Instructions for \\ Web Audio Evaluation Tool}
 \author{Nicholas Jillings, Brecht De Man and David Moffat}

 \tableofcontents
 
 \clearpage
 
 \section{Installation}
-	Download the folder (\url{https://code.soundsoftware.ac.uk/hg/webaudioevaluationtool/archive/tip.zip}) and unzip in a location of your choice, or pull the source code from \url{https://code.soundsoftware.ac.uk/hg/webaudioevaluationtool} (Mercurial). 
+	\label{sec:installation}
+	Download the folder (\url{https://code.soundsoftware.ac.uk/hg/webaudioevaluationtool/archive/tip.zip}) and unzip in a location of your choice, or pull the source code from \url{https://github.com/BrechtDeMan/WebAudioEvaluationTool.git} (git) or \url{https://code.soundsoftware.ac.uk/hg/webaudioevaluationtool} (Mercurial). 
 	
 	\subsection{Contents}
 		The folder should contain the following elements: \\
 		
 		\textbf{Main folder:} 

 		
 		The tool is platform-independent and works in any browser that supports the Web Audio API. It does not require any specific, proprietary software. However, in case the tool is hosted locally (i.e. you are not hosting it on an actual webserver) you will need Python (2.7), which is a free programming language - see the next paragraph. 
 	
 \clearpage
 
+\section{Quick start}
+	This document aims to provide an overview of all features and how to use them. However, if you are just trying out this tool, or you need to put together a test very quickly, or you simply don't want to read through all the details first, this section gives you the bare necessities to put together a simple listening test very quickly. 
+
+	\begin{itemize} % WIP
+		\item Download the tool (see Section~\ref{sec:installation})
+		\item Copy the tool to a PHP-enabled web server if you have access to one. 
+		\item Go to \path{test\_create.html} and configure your test.
+		\item Your test will be live at \path{[web server address]/index.html?url=[testname].xml}. If you are not using a web server, you can simulate one locally by running 
+		\path{scripts/pythonServer.py} (requires Python), after which you can access the test at \\ % hack
+		\path{http://localhost:8000/index.html?url=[testname].xml}
+	\end{itemize}
+
+\clearpage
 
 \section{Test setup} % TO DO: Linux (Android, iOS)
 
 	\subsection{Sample rate}
 		Depending on how the experiment is set up, audio is resampled automatically (the Web Audio default) or the sample rate is enforced. In the latter case, you will need to make sure that the sample rate of the system is equal to the sample rate of these audio files. For this reason, all audio files in the experiment will have to have the same sample rate. 

 \section{Terminology} % just to keep track of what exactly we call things. Don't use terms that are too different, to avoid confusion.
 	As a guide to better understand the Instructions, and to expand them later, here is a list of terms that may be unclear or ambiguous unless properly defined. 
 	\begin{description}
 		\item[Subject] The word we use for a participant, user, ... of the test, i.e. not the experimenter who designs the test but the person who evaluates the audio under test as part of an experiment (or the preparation of one). 
 		\item[User] The person who uses the tool to configure, run and analyse the test - i.e. the experimenter, most likely a researcher - or at least 
-		\item[Page] A screen in a test; corresponds with an \texttt{audioholder}
+		\item[Page] A screen in a test
 		\item[Fragment] An element, stimulus or sample in a test; corresponds with an \texttt{audioelement}
 		\item[Test] A complete test which can consist of several pages; corresponds with an entire configuration XML file
 		\item[Configuration XML file] The XML file containing the necessary information on interface, samples, survey questions, configurations, ... which the JavaScript modules read to produce the desired test.
 		\item[Results XML file] The output of a successful test, including ratings, comments, survey responses, timing information, and the complete configuration XML file with which the test was generated in the first place. 
 	\end{description}