%% LyX 1.3 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[english]{article}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}

\makeatletter
\usepackage{babel}
\makeatother
\begin{document}

\title{Creating and Maintaining of Code Documentation}


\author{Chavdar Botev}


\date{1 June 2005}

\maketitle

\section{Introduction}

This document contains:

\begin{itemize}
\item Description of the documentation structure
\item Guidelines for creating documentation
\item Guidelines for maintaining documentation
\item Notes on the integration with the build process
\end{itemize}
This document should be used by members of the Cornell Database Group
participating in shared development projects. It is particularly aimed
at projects like dbgroup-utils, the quark-related projects, etc. These
projects share common development guidelines and build process. Additionally,
members join and leave these project on a continuous basis. Therefore,
it is very important such a consistent level of documentation is maintain
which will allow new people to easily join these projects.


\section{Locations and Structure}

Every repository supports both global, repository-wide and per-library/per-executable
documentation. In the first case, the documentation files are in a
root \texttt{docs/} directory. In the second case, the documentation
is in a docs directory right under the top-level target directory.
E.g. for \emph{corelib} the documentation will be under \texttt{corelib/docs/}.
The above directories are mandatory and are present in every repository/library/exectuables
no matter if there are any documents.

The \texttt{docs/} directory can contain zero or more documents. Each
document must be saved in its own directory, which it should contain
all the files used by the document. 

Files that should be converted by the build process should be placed
in directories named \texttt{XXX-sources/} where \emph{XXX} describes
either the purpose of the files in it. Good names are \texttt{figures-sources/},
\texttt{chapter1-sources/}, etc. In such directories, supported formats
will be converted; the other files will not be processed. All other
directories are assumed to contain files that cannot be converted
and their contents will be copied literally. The \texttt{pdf/} and
\texttt{html/} directories have special purpose. These should contain
the PDF and HTML version of a document, that cannot be automatically
converted to these formats. It is a responsibility of the author of
the document to create and keep up-to-date these directories.


\section{File Formats}

Documents are encouraged to be in open formats. The use of closed
document formats like Microsoft Word, Microsoft Visio, etc. is strongly
discouraged. For example, \LaTeX{} or Lyx are preferred to MS Word;
SVG,XFig,Sketch,Dia are preferred to Microsoft Visio, WMF, etc. For
raster graphics format use either PNG for lossless compression or
JPG for greater compression. File formats like GIF and BMP should
be avoided. For vector graphics format, the prefered formats are PS/EPS,
XFig, and SVG. 

Whenever possible, one should use document formats and programs that
support automatic, command-line processing converting to other formats.
For example, \LaTeX{} files can be converted to html, pdf, etc. while
MS Word files cannot. In cases where such covnersion is possible,
only the source files used for generation should be committed. The
build process should take care of the conversion. If the build process
does not support a certain file format, the person(s) responsible
for the build process should be contacted to add such support.

If a file cannot be automatically converted, then both the original
file and the converted file should be submitted. It is very important
that both versions are submitted so other people can later modify
the documentation without having to recreate parts of it.


\section{Integration with the Build Process}

The main goal of the build process for the documentation is to create
HTML and PDF versions of the documents. If the documents are in a
format the supports automatic conversion to HTML and PDF (e.g. LaTex),
the build process will do that. Otherwise, the authors of the document
should check in the documentation sources and its HTML and PDF versions
that are created manually. 

The generated documents for a library or executable are stored under
\texttt{docs/} in the distribution directory for the library or the
executable. For example, the documentation for \emph{corelib} will
be stored in \texttt{distrib/corelib/docs/}. The PDF version will
be stored in a \texttt{pdf/} subdirectory (\texttt{distrib/corelib/docs/pd}f\texttt{/})
and the HTML version will be stored in a \texttt{html/} subdirectory
(\texttt{distrib/corelib/docs/html/}).

The same applies for repository-wide documentation files. They are
stored in \texttt{distrib/docs/} with \texttt{pdf/} and \texttt{html/}
subdirectories.

The documentation files can be build using several build targets.

\begin{itemize}
\item \emph{docs} - creates all documents, repository-wide and per-library/executable
\item \emph{global-docs} - creates only the repository-wide documents
\item \emph{docs-<target>} - creates only the documents for the specified
library or executable <target>
\end{itemize}

\end{document}
