Subject: [tryton] Re: Tryton Documentation Framework - my opinion

From: Igor Támara <[email-masked]>
Date: Sun, 2 Nov 2008 13:12:32 -0500

Hi, the neat ideas proposed here remind me that succesful  projects
have tons of good documentation, to mention postgresql, python and
apache. You can take a look at [1], where the docs are an important
part of them, you can see that fact visually.   If we are able to
have a infrastructure as proposed and a team of "docers", Tryton
will be the ERP of reference.  Well there are a kloc to be written
and tklod(tens of kilolines of documentation) too.

1.http://vis.cs.ucdavis.edu/~ogawa/codeswarm/

Just my 0.00000002 cents

-- 
Recomiendo la wikipedia, una enciclopedia que evoluciona día a día
http://es.wikipedia.org

---

From: Igor Támara <[email-masked]>
Date: Fri, 31 Oct 2008 05:46:32 -0500

Hi, 
Cédric> On 30/10/08 23:22 -0700, udono wrote:
Cédric> > 
Cédric> > additional:
Cédric> > For module documentation we need to have an appropriate inheritance
Cédric> > mechanism like the Tryton inherit. Because the highly generic module
Cédric> > design of Tryton will produce a bunch of addon modules with additional
Cédric> > functioning. This functionality is usually introduced by inheriting
Cédric> > end extending depending modules. So we need a mechanism which is able
Cédric> > to understand which modules are installed and how addon modules extend
Cédric> > the documentation of other modules. This additional Documentation from
Cédric> > other modules need to be "inserted" into the appropriate documentation
Cédric> > of the main documentations.
Cédric> > Maybe this can be done with Sphinx variables and a helper function
Cédric> > like the old 'gen_graph.sh'?
Cédric> 
Cédric> I don't aggree. The documentation of one module must just explain what
Cédric> the module does. If there is inheritage in it, it must just explain what
Cédric> it adds or removes to the main object.
Cédric> 

That would be, linked to the parent(s), just a link to them, If the
module is installed the parents also are, and links would be
appropiate on the module doc.

Cédric> -- 
Cédric> Cédric Krier
Cédric> 
Cédric> B2CK SPRL
Cédric> Rue de Rotterdam, 4
Cédric> 4000 Liège
Cédric> Belgium
Cédric> Tel: +32 472 54 46 59
Cédric> Email: [email-masked]
Cédric> Jabber: [email-masked]
Cédric> Website: http://www.b2ck.com/

-- 
Recomiendo Inkscape para hacer gráficos vectoriales
http://www.inkscape.org

---

From: Cédric Krier <[email-masked]>
Date: Fri, 31 Oct 2008 10:01:37 +0100

On 30/10/08 23:22 -0700, udono wrote:
> 
> additional:
> For module documentation we need to have an appropriate inheritance
> mechanism like the Tryton inherit. Because the highly generic module
> design of Tryton will produce a bunch of addon modules with additional
> functioning. This functionality is usually introduced by inheriting
> end extending depending modules. So we need a mechanism which is able
> to understand which modules are installed and how addon modules extend
> the documentation of other modules. This additional Documentation from
> other modules need to be "inserted" into the appropriate documentation
> of the main documentations.
> Maybe this can be done with Sphinx variables and a helper function
> like the old 'gen_graph.sh'?

I don't aggree. The documentation of one module must just explain what
the module does. If there is inheritage in it, it must just explain what
it adds or removes to the main object.

-- 
Cédric Krier

B2CK SPRL
Rue de Rotterdam, 4
4000 Liège
Belgium
Tel: +32 472 54 46 59
Email: [email-masked]
Jabber: [email-masked]
Website: http://www.b2ck.com/

---

From: udono <[email-masked]>
Date: Thu, 30 Oct 2008 23:22:32 -0700 (PDT)

additional:
For module documentation we need to have an appropriate inheritance
mechanism like the Tryton inherit. Because the highly generic module
design of Tryton will produce a bunch of addon modules with additional
functioning. This functionality is usually introduced by inheriting
end extending depending modules. So we need a mechanism which is able
to understand which modules are installed and how addon modules extend
the documentation of other modules. This additional Documentation from
other modules need to be "inserted" into the appropriate documentation
of the main documentations.
Maybe this can be done with Sphinx variables and a helper function
like the old 'gen_graph.sh'?
--~--~---------~--~----~------------~-------~--~----~
[email-masked] mailing list
-~----------~----~----~----~------~----~------~--~---

---

From: udono <[email-masked]>
Date: Thu, 30 Oct 2008 08:17:32 -0700 (PDT)

errata:
s/gettext/babel

---

From: udono <[email-masked]>
Date: Thu, 30 Oct 2008 07:52:27 -0700 (PDT)

(With this topic I like to initiate a discussion about a documentation
framework for Tryton. There is no hurry to be ready for the first
release i think, because IMHO we are on the right road.)

Some topics to consider for a documenting framework:
1. Tryton is a software product. Documentation is part of the product.
We need to integrate documentation into the product (package) but hold
the technology dependencies low.
2. Tryton is a community driven product, so it needs to make
documentation contributions as easy as possible.
3. Tryton aims to be multi lingual on all user interfaces
4. Tryton is a modular application with three main parts: server,
client, modules. All of these parts needs an own documentation.
5. Tryton is under steady development and will be released "often", so
we need different documentations which fits to different releases.
6. Tryton aims to be high quality, so documentation needs to be
controlled

I highly encourage the decision to use sphinx and restructured text as
the documenting generator for Tryton. Sphinx take care of my 1. topic.
It is easily included into the Tryton package, no internet need for
reading documentation. Sphinx gives possibility for customising with
python, no extra technology needed, like php on mediawiki for
example.
Sphinx even take care of my 4. topic, because of its small overhead,
we can have specific documentation distributed with the client, the
server and each module.
My 5. topic is solved with sphinx, too. Because we release Tryton
packaged with its specific documentation the user have his
documentation fit to the Tryton version.

The 6. topic is solved politically via Sphinx, IMHO the right way. Let
me go into greater detail for this topic. I often experienced, when a
project decide to use a community driven wiki, their maintainers wants
to get rid of the responsibility for all the time consuming
documentation things. In their binary minds ;-) developers often think
of something like: We are doing the code and the user-community
explains how it works. In clear words: These maintainers move the
responsibility for the main documentation of their software product to
the community which uses the software. This way is doomed from the
begining, IMHO.
I haven't seen many projects where the user-community is able to lift
the weight of creating a good main user documentation. I often
expected a learning factor on maintainer side to see, that it doesn't
work the way they like it. But wrong, often they fight their self
declared freedom from the documenting things. So very often I see
promising offerings of "Community contributions welcome!" like "You
are invited to make this Wiki grown complete and up to date". This
appeal often comes together with a hidden blame to the community: "If
you (user) dislike the incompleteness, aged and chaotic informations
on our wiki pages, then its up to You to write the documentation
better, you can not come and bother us, we have more important jobs to
do..."
Even I called this "spell of protection" myself often on newsgroups in
my former projects, I became to dislike this way of demand the
community participation. But I understand the main intention of these
maintainers/developers as well: To less people for to much work to do.
So sourcing out the most time-consuming and cumbersome parts is the
main aspect of using a Wiki for documenting a software product. As I
told before, I see this idea as a bad one and as doomed from the
beginning. Why? Because documentation is the most important part
besides the software self. You simply can not source it out of the
projects responsibility.

So our decision to put the documentation into the Tryton package is
the clear statement of the tryton project, to be responsible for the
documentation. If the Tryton documentation is bad, the blame for this
is addressed to /us/ the Tryton project.

Now I come back to the other topics I mentioned above. There are some
points which are not covered by Sphinx. Namely translation and
community participation.
About translation: Version 0.5 of sphinx will have translatable link
buttons and texts, so we need to wait for this. AFAIK it doesn't
include a mechanism for translating its contents, so its up to us
doing this, maybe in a contribution to the sphinx project.
On our meeting b2ck told a firstly strange idea to me. Using gettext
for documentation translations... gettext is good enough for
translating word or sentences, but whole documents? I thought about
this thing and digged in the internet. Their idea became a 'very good
idea' to me, as I reflect of...
Gettext is great for translating, because it is able to signal if a
source text has changed. You see this on the yellow background of
phrases in poedit, which indicates: "The source string has changed,
please check your translation if it fit any longer".
Translating singular sentences is to atomic and translating and
updating complete documents is a hard work for identifying small
changes. But we can do a translation for each paragraph of a source
document. With gettext we are able to indicate in the sphinx documents
parts of translations as outdated (make them a light yellow
background). With gettext we are able to show on-mouse-over the
original English text for each paragraph. This is used by tikiwiki you
may browse for further informations: http://www.wiki-translation.com/tiki-index.php
and on this slides you will find what I mean:
http://wiki-translation.com/tiki-download_wiki_attachment.php?attId=2

About community participation: For this b2ck suggested another
promising idea: Using mercurial as a revision instrument for
documentation changes and the depending translations. I find this
promising, because we do not need another technology as we are using
now, and it is like sphinx customisable.
A first and silly thing I did was to put an "edit source" link to the
shinx documentation. This opens in your favourite editor the original
documentation document you are showing. See
http://groups.google.com/group/tryton/browse_thread/thread/7928ce1c24f7d80e
for further informations.

For me we need just some glue between gettext mercurial and sphinx to
get a great framework for translatable documentations.

With this few words ;-) I like to open the discussion...
--~--~---------~--~----~------------~-------~--~----~
[email-masked] mailing list
-~----------~----~----~----~------~----~------~--~---