openerp-expert-framework team mailing list archive

[Ferdinand Gassauer <office@xxxxxxxxxx>]

Am Samstag 12 Dezember 2009 13:09:17 schrieb Simone Orsi:
> Hi Albert,
> 
> On 12/09/2009 11:55 PM, Albert Cervera i Areny wrote:
> > Here's a proposal I made some time ago. Given that now there's a
> > framework expert's group, here's my second try:
> >
> > I think docs should be integrated with modules. I wanted to make a
> > proposal for a documentation system for OpenObject. Let me explain it
> > here.
> >
> > I'd use DocBook with XML for documentation. Simply because it's easily
> > parseable. I think each paragraf and title should have an id which could
> > then be referred by modules that depend on the current module, just like
> > views work. For example:
> >
> > Module T:
> >
> > <title id="summary">Summary</title>
> > <para id="intro">
> > This is a summary of the module one that does this.
> > </para>
> >
> > Module TT (which depends on T):
> >
> > <para id="intro" position="replace">
> > This is a summary of the module one that does this and that.
> > </para>
> >
> > Of course, there would be "replace", "before", and "after" options as
> > always. Also you could add special tags in the code (which docbook
> > automatically ignores), like a field reference:
> >
> > <para id="explanation">
> > The invoicing process won't work unless partner's <field
> > ref="res.partner.vat">vat</field> field has a correct value.
> > </para>
> >
> > This "extra" information, would be parsed when the module is installed
> > and appended to field documentation so when the user sees a question marc
> > in a field sees current documentation plus theh places where the field is
> > referred to in other parts of the documentation.
> >
> > For example, in the "res.partner.vat" case one would see:
> >
> > """
> > Description: Value Added Tax number. Check the box if the partner is
> > subjected to the VAT. Used by the VAT legal statement
> >
> > References:
> >
> > * .... The invoicing process won't work unless partner's vat field has a
> > correct value. ....
> > """
> 
> I don't think it'd be a good idea to place extra info for fields into
> the docs. Fields have to be documented in the code.
> 
> > Well, I think you get the idea of the whole thing. I believe something
> > like this would make OpenERP have an incredible documentation system I
> > doubt others have.
> >
> > If people contribute or not to the docs is a matter of forcing people to
> > do so. For example, in PostgreSQL absolutely no patch gets commited if it
> > doesn't change docs acordingly. Without commitment no doc system will be
> > useful.
> 
> True
> 
> > By the way, I'm willing to implement this system if the we agree this
> > will be OpenObject's way of document things. But we need to agree on that
> > first.
> 
> +1
> 
please do not forget to implement a possibility to add site and/or company 
specific documentation.
-- 
Best Regards

ChriCar Beteiligungs- und Beratungs- GmbH
http://www.chricar.at/ChriCar/index.html
Dr. Ferdinand Gassauer
Official Tiny Partner