openerp-expert-framework team mailing list archive

[Albert Cervera i Areny <albert@xxxxxxxxxxx>]

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. ....
"""


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.

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.

-- 
Albert Cervera i Areny
http://www.NaN-tic.com
Mòbil: +34 669 40 40 18