- 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
This commit is contained in:
parent
72fac2b901
commit
1515b2065f
|
@ -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 % --------------------------------------------------
|
||||
|
|
Loading…
Reference in New Issue