- Added norms about documentation guidelines by Djina

- Integrated draft about Mailing List usage (adaptation)


git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@205 3ecf2c5c-341e-0410-92b4-d18e462d057c

doc/sgpem2dman.texi

@@ -67,6 +67,9 @@ Free Documentation License''.
 
 * Directory overview:: How SGPEM sources are organized
 
+* Writing documentation:: How to write formal documents
+                          for draft approval
+
 * Coding style::  Here there are the rules you should abid
                   to when working on SGPEM
 
@@ -75,6 +78,9 @@ Free Documentation License''.
                        our repository, and how we would
                        like you to commit patches
 
+* Using the Mailing List:: How to compose your messages
+                           when contacting us on the ML
+
 * License:: The full text of the license under which this
             manual is given to you
 
@@ -90,6 +96,13 @@ Free Documentation License''.
 
 @table @strong
 
+@item 2006, January 26th, @r{--- Matteo Settenvini}
+Added reference subsection about documenting code. Added
+decisional and communicative norms.
+
+@item 2006, January 26th, @r{--- Djina Verbanac}
+Added section about the writing of documentation
+
 @item 2006, January 24th, @r{--- Luca Vezzaro}
 Updated some code snippets whose style were
 inconsistent with our coding rules. Added the point on
@@ -112,7 +125,7 @@ First draft of this document
 
 @c % --------------------------------------------------
 
-@node    Directory overview, Coding style, History, Top
+@node    Directory overview, Writing documentation, History, Top
 @chapter Directory overview
 @cindex  directory layout
 
@@ -159,10 +172,178 @@ The source files of SGPEM.
 
 @end table
 
+@c % --------------------------------------------------
+
+@node    Writing documentation, Coding style, Directory overview, Top
+@chapter Writing documentation
+@cindex  documentation
+
+@section Formal documents and 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}.
+
+In some cases also use some other subsections of @emph{OpenOffice.org}
+will be used, like @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 
+explained hereafter.
+
+@itemize
+@item
+@emph{All the document start with the 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 
+technical document. Under the title goes the @b{acronym} of the project 
+(@acronym{SGPEMv2}), followed by the @b{version} of the document. 
+
+Versions use the format @samp{x.y}, where both @samp{x} and @samp{y} 
+are integers. Minor changes to the document, like grammatical and 
+spelling corrections comport the increment of @samp{y}, while structural
+or significant changes (for example, changing the way to resolve a 
+specific problem) comport the increment of @samp{x}. 
+
+After the version number, it comes the @b{date} of the last modification 
+made to the technical document. At the end of the cover page it should
+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 
+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 
+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.
+
+@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.
+
+@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}.
+
+@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. 
+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}.
+
+@item
+At the end of every document there must be a @b{Glossary}. The Glossary 
+is a file on its own (usually the @file{docs/externals/Glossary.odt} 
+document in the repository), so new entries must be inserted in it.
+
+Every technical document should include the aforementioned file. 
+Please refer to the OpenOffice.org manual about @emph{Sections} to know
+how to do so. The Glossary will then be bound to the document dinamically,
+and every change on the Glossary will reflect in a change in all
+the documents that are linked to it.
+
+In this way all the technical documents will automatically contain the 
+latest up-to-date version of the Glossary.
+
+@item
+The @b{Header} of all pages, except the one on the cover page, 
+contains:
+
+@itemize
+@item 
+in the left corner, the name of the company;
+
+@item
+in the right corner, the Chapter number and name.
+@end itemize
+
+@item
+The @b{Footer} of every page, except the cover page, contains:
+
+@itemize
+@item
+in the left corner, the title of the document followed by the date of 
+the last modification;
+
+@item
+in the right corner it contains the number of the page due to the total 
+number of  pages.
+@end itemize
+
+@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.
+
+
+@c % ---- new subsection 
+
+@subsection Documenting code
+
+In order to generate documentation straight from the source code:
+
+@subsubsection C++ code
+
+Please refer to 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.
+
+In particular, for functions and methods, you should use
+@code{\param} and @code{\return} to describe respectively
+parameters and return value of it.
+
+@subsubsection Python code
+
+It is usually possible to document 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.
+
 
 @c % --------------------------------------------------
 
-@node    Coding style, Committing changes, Directory overview, Top
+@node    Coding style, Committing changes, Writing documentation, Top
 @chapter Coding style
 @cindex  coding style
 
@@ -604,7 +785,7 @@ If you need a smart pointer, be sure to check out
 
 @c % --------------------------------------------------
 
-@node    Committing changes, License, Coding style, Top
+@node    Committing changes, Using the Mailing List, Coding style, Top
 @chapter Committing changes
 @cindex  repository
 @cindex  subversion
@@ -862,10 +1043,190 @@ practice, locking seems to inhibit productivity more than anything else.
 @end quotation
 @cite{Version Control with Subversion, a.k.a. ``The Subversion Book''}
 
+
+@c % --------------------------------------------------
+
+@node    Using the Mailing List, License, Committing changes, Top
+@chapter Using the Mailing List
+@cindex  mailing list
+
+@subsection Introduction and goals
+
+This mailing list (often referred from now on simply as ``ML'') has been
+created with the specific aim of coordinating the effort of the members
+of our Software Engineering steering committee.
+
+This chapter focuses on describing a set of guidelines of what
+should be considered best practices whenever writing to the ML, 
+in order to avoid possible troubles and thornful outcomes.
+
+This very chapter (an approved draft) you're reading can be amended 
+too. For more informations, please refer to the corresponding 
+subsection, called ``A democratic discussion''.
+
+@subsection About the language, some useful conventions
+
+The English language (either the UK or the US one, but the slangwords)
+is believed to be the best choice to deliver our internal
+drafts and user manuals, while the external ones are kept in Italian 
+to help our Customer in his revision work. 
+
+The decision of internally using the English language descends 
+from two considerations:
+
+1) English is probably the most widely used language in the world (at
+least taking in account geographical extension). Making an effort to use
+it correctly during the development of this project is a good training
+ground for the future, and makes @acronym{SGPEMv2} usable also by
+non-Italian speakers.
+
+2) It encourages you to use a cleaner and simplier form, since 
+you're writing in a foreign language: you actually have to think 
+about what you're doing in a more careful way; not only to express 
+your ideas, but also to express your ideas @emph{in a way you can be 
+understood}. Most people that don't read again what they typed if 
+writing in their mothertongue, usually look through an email 
+composed in English at least twice, in order to check out for grammar
+mistakes. Therefore, it often makes easier to find also conceptual 
+disasters.
+
+Please avoid strong words or offensive language. They don't help the
+discussion anyway, they represent a waste of bytes on the server, and
+at least some of us consider them to be childish behaviour.
+
+If some of us ask you to explain what you meant, or correct your
+grammar, please don't lose your temper or feel blue: we're all here to
+learn.
+
+As a side note, we encourage the use of the "singular they" as a neutral
+form. You can find a nice article on this by searching @emph{Wikipedia}.
+
+This doesn't forbid you to use Italian for normal communications over
+the ML.
+
+@subsection Steer the wheel
+
+Most discussions start with a draft, like this. The talking then goes on
+amendating the document and, when no-one opposes it anymore, the draft is
+marked as an approved guideline, and everybody is meant to (as strictly
+as possible) abide to it.
+
+Exceptions or revisions to guidelines due to a rework done by some other
+process pertain to the @acronym{KA,Knowledge Area} of 
+Process Improvement (see @acronym{SWEBOK} §9).
+
+The committer could ask for some particular modalities in carrying out
+this procedure, although unlikely (usually, it's an internal task).
+
+This draft is hence subject to change in this aspect.
+
+@subsection A democratic discussion
+
+Of course, not everybody has to agree with everyone else on every
+subject. We're just humans, after all; we're entitled to our opinion.
+Hence, it may be necessary, at times, to set up a votation.
+
+In a votation, if @samp{n} options are available, each voter has
+@samp{n*10} points expendable. They can thus weight their decision
+prioritizing one or more of the listed choices, and distributing these
+points as they wish. The highest scoring option wins the votation. 
+In case of even scores, ballot can happen until a clear decision 
+has been reached.
+
+Usually a maximum time to amendate a draft or to vote is declared; 
+if no further points to discuss are raised in such time, the document 
+is marked as agreed. The minimum number of days for a votation / to amend 
+a draft is set to three.
+
+@subsection Keeping the archives clean
+
+If, by writing your response, you've to comment on things that pertain to
+@emph{different} @acronym{KA}s, or if the discussion requires to 
+be "branched" over different subjects, please also start a new thread, 
+change the subject line, and split your own letter, even if the answer 
+to a question just takes two lines.
+
+Not only this makes easier to search throughout the archives; it makes
+easier for others to reply only to those matters that concern they,
+tidily continuing the tree structure of threads.
+
+@subsection Diving in technicalities
+
+E-mails should be sent out text-only, not in @acronym{HTML} format. 
+This makes them faster to download, store, manipulate, and it even 
+saves us from kaki-on-pink kitsch backgrounds. 
+Moreover, text-only mails are (almost always) monospaced; this allows 
+the more aestethical-inclined of us to integrate @acronym{ASCII}-art 
+in them, like handmade diagrams.
+
+Virtually all email clients available let you choose how you want to
+send your messages to a certain address: if in @acronym{HTML}, 
+plain-text or both. Please choose plain-text only.
+
+Another important thing to keep in mind, is to set your encoding to
+@acronym{UTF}-8. This makes interoperability between different and exotic
+encodings possible by using a standard base. Yes, even between different
+operating systems, like the one called ``98'' and the one named ``2000'' @emph{;-)}.
+
+A simple discussion shouldn't be marked in whatever way: it has just a
+meaningful subject. For example: @emph{``hello, world!''} is a bad subject; it
+doesn't tell much of the contents of the message, besides that probably
+it has some form of salute into it. Also, a line like 
+@emph{``i've a problem''} is a bad one: it could be a problem in 
+installing an operating system, in finding a bug in a program, or 
+in carrying out the rubbish and feeding the cat.
+
+An example of a good subject is @emph{``Possible buffer overflow in
+recursive-sort.cc:374''}. Also @emph{``How can I stuff my cat with 
+friskies?''} is a good one, albeit maybe a little bit off topic.
+
+For documents like this, a subject line of the form @emph{``(draft)
+<description>''} is a good choice. It makes it easily recognizable, and
+it's like automatically asking for people to amend.
+
+Approved drafts are marked with a date, and are copied in a separate
+directory of the repository (tipically, a @samp{doc} subdirectory). A quick
+TeXinfo rewrite can be performed if need arises, or if someone is willing
+to spend five minutes doing so.
+
+Every approved document contains the full text correctly amended
+(whereas, during the discussion just snippets of it are changed by
+diff), and starts with a date and a progressive number in its header.
+The header should be in the form:
+
+@example
+----------------------------------------
+
+(approved draft) #xxxx, [<area>]
+Initially submitted by: <Name Surname>
+On date: <YYYY, Month DD>
+Approved by:
+     <Name Surname 1>
+     <Name Surname 2>
+     ...
+Rejected by:
+     <Name Surname 1>
+     ...
+Reason of refusal:
+    <description of the reason>
+Finally approved on date: <YYYY, Month DD>
+
+----------------------------------------
+@end example
+
+Of course, the @samp{``rejected by''} list should ideally be empty, or just
+listing @samp{``nobody''}. The subject area is up to the writer to purpose,
+wisely. Different areas are instantiated as need arises. Please don't
+create a forest of areas; it's no use whatsoever.
+
+Have fun, and ...
+
+... happy hacking!
+
 @c % --------------------------------------------------
 
 @c include license text
-@node License, Concept index, Committing changes, Top
+@node License, Concept index, Using the Mailing List, Top
 @include fdl.texi
 
 @c % --------------------------------------------------