- Fix grammar and form in chapter "2.Writing documentation"

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@237 3ecf2c5c-341e-0410-92b4-d18e462d057c
This commit is contained in:
tchernobog 2006-01-27 15:33:32 +00:00
parent 042549c290
commit cc7851daf9
1 changed files with 79 additions and 67 deletions

View File

@ -93,6 +93,7 @@ Free Documentation License''.
@node History, Directory overview, Top, Top
@unnumbered History
@cindex history of changes
@table @strong
@ -136,6 +137,7 @@ First draft of this document
@node Directory overview, Writing documentation, History, Top
@chapter Directory overview
@cindex directory layout
@cindex source code organization
If you need to work on SGPEM sources, you'll probably
be interested in understanding how this package directory
@ -201,25 +203,28 @@ The source files of SGPEM.
@node Formal documents and draft proposals, Documenting code, Writing documentation, Writing documentation
@section Formal documents and draft proposals
@cindex formal documents
@cindex draft proposals
@subsection Introduction
For writing and editing technical documents we use a subsection
of the free office suite @emph{OpenOffice.org 2.0.0}, namely @emph{OpenOffice.org Writer}.
of the free (as in speech) office suite @emph{OpenOffice.org 2.0.0},
namely @emph{OpenOffice.org Writer}.
In some cases also use some other subsections of @emph{OpenOffice.org}
will be used, like @emph{OpenOffice.org Calc} for calculations and
We sporadically also use other parts of the suite, such as
@emph{OpenOffice.org Calc} for calculations and
charts, and @emph{OpenOffice.org Impress} for presentations.
@subsection Technical document format
All technical documents must respect the styles and formats
All technical documents must respect the style and formats
explained hereafter.
@itemize
@item
@emph{All the document start with the Cover Page} :
@emph{All the documents start with a Cover Page} :
The @b{cover page} contains in the right corner the logo, name and address
of company. In the middle of the page there's the @b{title} of the specific
of the company. In the middle of the page there's the @b{title} of the specific
technical document. Under the title goes the @b{acronym} of the project
(@acronym{SGPEMv2}), followed by the @b{version} of the document.
@ -235,53 +240,55 @@ be reported the @b{status} of the document, either @emph{Formal} or
@emph{Informal}, followed by one of the tags @emph{External} or
@emph{Internal}.
The @b{footer} of the cover page must contain the name of the @b{Author} of
The @b{footer} of the cover page should contain the name of the @b{Author} of
that technical document.
@item
The page after the cover page has to contain:
@enumerate
@item
@strong{Distribution List}: to whom the document goes, it includes
the Surname and Name of the person to who delivers the document along with
the role of that person.
@item
@strong{History of changes} : where to trace the changes made to the specific
document, including the date of the change, the person who made the
@strong{Distribution List}: to whom the document goes. It includes
the Surname and Name of the person to be reached by the document,
along with the role of that person.
@item
@strong{History of changes}: where to trace the changes made to the
document, including the date of the edit, the person who made the
change, and the reason(s) of it.
@item
@strong{List of Approved Versions} : here all the approved versions of
that document are traced, reporting the date and the name of the
person who approved that version.
@strong{List of Approved Versions}: here are traced all the approved
versions of the document, reporting the date and the name of the
person who approved that particular revision.
@end enumerate
@item
An @b{Abstract} must follow the List of Approved Versions: a short
one-liner of what the document is about.
An @b{Abstract} has to follow the List of Approved Versions: it's
a short one-liner of what the document is about.
@item
On a new page, there's a @b{Table of Contents} that shows all
the @b{Headings} in the file.
If the document has a lot of Illustrations, then after the @b{Table of
Contents} it should follow a @b{Illustration Index} of all figures
included in the file.
If the document includes a lot of figures, then after the @b{Table of
Contents} there should be an @b{Illustration Index}.
@item
After that, every document has to start with the @b{Introduction} section,
where it will be described the purpose of the document, the purpose
of the product and it will be included a list of used @b{References}.
where it will be described the purpose of the document and the purpose
of the product, along with a list of used @b{References} to other
documents or resources.
@item
The other parts of the document are specific to the technical document
itself, and therefore should be managed by the author of the document.
Other parts of the document are specific to the technical document
itself, and therefore should be managed by the editor.
Mostly, the general structure for the more common documents can be found at
@uref{http://www.math.unipd.it/~tullio/IS-1/2005/Progetto/Documenti.html}
(in Italian).
In the @samp{docs/misc/} directory of the Subversion repository,
there's an OpenOffice.org @b{template} with some already defined
styles you should inherit from. Its name is @file{templatedocument.ott}.
@ -289,16 +296,16 @@ styles you should inherit from. Its name is @file{templatedocument.ott}.
@item
At the end of every document there should be a @b{Glossary}. The Glossary
is a file on its own (usually, @file{docs/externals/Glossary.odt}
off the repository), so new entries must be inserted into it.
off the repository), so new entries must be inserted into this latter.
Every technical document should ``include'' the afore mentioned file.
Please refer to the @emph{OpenOffice.org} manual about @emph{Sections} to know
how to do so. The Glossary will then be linked to the current document
how to do so. The Glossary will so be linked to the current document
dinamically, and every change done on the Glossary will reflect
in an automatical update in every linker.
in an automatic update in every referer.
In this way all the technical documents will automatically contain the
latest up-to-date version of the Glossary.
In this way all the technical documents are always able to have the
latest up-to-date and synchronized revision of the Glossary.
@item
The @b{Header} of all pages, except the one on the cover page,
@ -309,11 +316,11 @@ contains:
in the left corner, the name of the company;
@item
in the right corner, the Chapter number and name.
in the right corner, the chapter number and name.
@end itemize
@item
The @b{Footer} of every page, except the cover page, contains:
The @b{Footer} of every page, except on the cover page, contains:
@itemize
@item
@ -327,10 +334,9 @@ number of pages.
@end itemize
To make easier to abid to these rules, inherit from the template document that
includes all Fonts and Styles established. It also has a foundation for all
the pages mentioned above.
To make it easier to abid to these rules, please remember to inherit
from the template document. It lays down a foundation for all
the style guidelines mentioned above.
@c % ---- new section
@ -340,46 +346,52 @@ the pages mentioned above.
In order to generate documentation straight from the source code:
@subsection C++ code
@cindex documenting C++ code
Please refer to Doxygen manual
Please refer to @emph{Doxygen} manual
(@uref{http://www.stack.nl/~dimitri/doxygen/manual.html})
in order to learn how to use this automatic tool for extracting
documentation from code.
Every function, class, class member, class method,
and enumeration in code should be documented, less of static
global functions visible only to the current compilation unit.
and enumeration in code should be documented, less of trivial
static global functions visible only to the
current compilation unit.
In particular, for functions and methods, you should use
@code{\param} and @code{\return} to describe respectively
parameters and return value of it.
parameters and return value.
@subsection Python code
@cindex documenting Python code
It is usually possible to document Python classes so that
It is usually possible to annotate Python classes so that
calling the @code{__doc__} method of an object returns
its documentation string.
Please refer to the Python manual at @uref{http://www.python.org/}
to learn more of it.
However, if we want to generate good documentation straight
from code with Doxygen, we should use the @samp{#} documenting
style. Please look at the end of
@uref{http://www.stack.nl/~dimitri/doxygen/docblocks.html} for an example.
from code, with the help of Doxygen, we should use the @samp{#}
documenting style. Please look at the end of
@uref{http://www.stack.nl/~dimitri/doxygen/docblocks.html} for
an example.
@c % ----- new subsection
@node Reporting anomalies, (none), Documenting code, Writing documentation
@section Reporting anomalies
@cindex anomaly
@cindex bug
@emph{Note}: sometimes we will refer to an anomaly with the less-formal
term ``@emph{bug}''.
Anomaly documentation is divided in two parts. The first part concerns the
@b{Anomaly Investigation} record and the second one the @b{Anomaly Resolution} record.
All informations about Anomalies are held in the Appendix section of
the document named @file{AnomalyRecords.odt}. If you find an anomaly you should start
a new page and create a header as follows:
@b{Anomaly Investigation} and the second one the @b{Anomaly Resolution}.
All informations about anomalies are held in the document named
@file{AnomalyRecords.odt}. If you find an anomaly you should start
a new page via a page-break, and create a header as follows:
@table @strong
@ -387,7 +399,7 @@ a new page and create a header as follows:
Identification number of the anomaly, a unique integer
@item Summary
A one-liner with a summary of the contents of the anomaly
A one-liner with a summary of the anomaly
@item Severity
This field describes the impact of a bug.
@ -408,10 +420,10 @@ This field describes the impact of a bug.
@end table
@item Reporter
Name and email of the person who discovered the Anomaly
Name and email of the person who discovered the anomaly
@item Date of Identification
GMT time at witch the anomaly was identified
Timestamp at which the anomaly was identified
@item Product type and version
Product (with version number) affected by the anomaly (e.g., architecture,
@ -420,7 +432,7 @@ design, code, documentation, @dots{}).
@item Status
Please choose one and only one of the following states.
These are used @strong{before} a resolution:
These are used @strong{before} reaching a resolution:
@table @samp
@ -449,7 +461,7 @@ These are used @strong{before} a resolution:
@end table
Instead, @strong{after} a resolution, the state should change to:
Instead, @strong{after} a resolution, the state should change to one of:
@table @samp
@ -474,8 +486,8 @@ Who's working to resolve this anomaly, name and email. Usually, it's initially l
@item Description and comments
Latin creativity at work -- text describing the reasons for assuming
the presence of an anomaly. Please be as clear as possible. Unfortunately, giving guidelines in this
sense is quite difficult @enddots{}
the presence of an anomaly. Please be as clear as possible. Unfortunately,
giving guidelines in this sense is quite difficult @enddots{}
As for follow-ups, always start with the name of the editor, email and the timestamp
of the comment, assigning a numerical ID to it.
@ -483,17 +495,17 @@ An example of a comment would be:
@smallexample
@group
-- Comment #1, Slartibartfast <slarti@@go.eu>, 2006 Jan 27th - 16:13 --
Okay, I'll go and fix the time-space continuum yesterday.
Okay, I'll go and fix the time-space continuum on last Friday 17th.
Just give me the time to put the gas in my spaceship, will you?
@end group
@end smallexample
@strong{Important}: please report clearly in a comment if you change any
field of the anomaly header.
@strong{Important}: please report it clearly in a new comment if you
change any field of the anomaly header.
@end table
When the anomaly is resolved, a footer to it is added, with:
When the anomaly is resolved, a footer is added to it, with:
@table @strong
@item Date