From 1515b2065f06c2667d22466390094e569d447ca8 Mon Sep 17 00:00:00 2001 From: tchernobog Date: Thu, 26 Jan 2006 14:21:07 +0000 Subject: [PATCH] - 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 | 369 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 365 insertions(+), 4 deletions(-) diff --git a/doc/sgpem2dman.texi b/doc/sgpem2dman.texi index 95257ee..7127233 100644 --- a/doc/sgpem2dman.texi +++ b/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) +''} 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, [] +Initially submitted by: +On date: +Approved by: + + + ... +Rejected by: + + ... +Reason of refusal: + +Finally approved on date: + +---------------------------------------- +@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 % --------------------------------------------------