From cc7851daf92be39f9c146196acf9456598adb0f9 Mon Sep 17 00:00:00 2001 From: tchernobog Date: Fri, 27 Jan 2006 15:33:32 +0000 Subject: [PATCH] - 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 --- doc/sgpem2dman.texi | 146 ++++++++++++++++++++++++-------------------- 1 file changed, 79 insertions(+), 67 deletions(-) diff --git a/doc/sgpem2dman.texi b/doc/sgpem2dman.texi index 807b0cd..0f4d014 100644 --- a/doc/sgpem2dman.texi +++ b/doc/sgpem2dman.texi @@ -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 , 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