%
% NOTE -- ONLY EDIT THE .Rnw FILE!!!  The .tex file is
% likely to be overwritten.
%
% \VignetteIndexEntry{Notes for writing introductory 'how to' documents}
%\VignetteDepends{}
%\VignetteKeywords{Expression Analysis}
%\VignettePackage{Biobase}
\documentclass[12pt]{article}

\usepackage{times}
\usepackage{hyperref}

\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textit{#1}}}
\newcommand{\Rmethod}[1]{{\texttt{#1}}}
\newcommand{\Rfunarg}[1]{{\texttt{#1}}}
\newcommand{\Rclass}[1]{{\textit{#1}}}

\textwidth=6.2in
\textheight=8.5in
%\parskip=.3cm
\oddsidemargin=.1in
\evensidemargin=.1in
\headheight=-.3in

\newcommand{\scscst}{\scriptscriptstyle}
\newcommand{\scst}{\scriptstyle}

\bibliographystyle{plainnat}

\begin{document}

\section*{How to write a HowTo}

One of the goals of the Bioconductor project is to produce (and
encourage others to produce) documentation on how to perform various
tasks. Our main interest is in tasks associated with computational
biology. However, we hope to produce HowTo documents for a wide
variety of tasks.

R has a very good mechanism for documenting individual functions,
methods and classes. However, there are many situations where the task
that we want to perform requires the use of many components. In other
cases we would like to document the overall purpose of an R package
rather than the individual functions. In this document we provide some
advice on how to construct a document to describe how to perform a task.

In most cases HowTo's will be written using \Rfunction{Sweave} in the
\Rpackage{tools} package.
In this document we give some general advice on how to write a HowTo.
Of courese there is no \textit{right} way to do this but we feel that we
can provide a few design principles that will help authors write
better HowTo's.


These design principles are listed below:
\begin{itemize}
\item It should be short (2 pages at most) and explicit.
\item It should be about a single topic.
\item It should contain runnable code and rely on data that are
  available in R or the libraries needed to carry out the task being
  documented.
\item HowTo's should not be about single functions. The function
  documentation is the right place to document that. HowTo's should
  document a process or task and will typically involve several functions.

\item To paraphrase Paul Halmos, you should imagine that you are
  writing a document for a friend who is as smart and has the same
  general level of knowledge as you but who does
  not know how to do the specific task at hand.

\item Make use of the indexing system. The title of the document should
be included in the \verb+% \VignetteIndexEntry+.
It should
contain the word \verb+HowTo+ to easily allow for programmatic
manipulation and sorting of the HowTo's.
\end{itemize}

\section{Session Information}

The version number of R and packages loaded for generating the vignette were:

\begin{verbatim}
<<echo=FALSE,results=tex>>=
sessionInfo()
@
\end{verbatim}

\end{document}