- 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
parent
042549c290
commit
cc7851daf9
|
|
@ -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.
|
||||
@enumerate
|
||||
|
||||
@item
|
||||
@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 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
|
||||
@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
|
||||
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.
|
||||
|
||||
@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
|
||||
|
|
|
|||
Loading…
Reference in New Issue