openerp-expert-framework team mailing list archive

[Simone Orsi <simone.orsi@xxxxxxxxxxxx>]

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


-- 
Simone Orsi              simone.orsi<at>domsense.com
Via Alliaudi, 19 - 10064  -  Pinerolo (TO)  -  Italy
Mobile: (+39) 3475004046  -   Fax: (+39) 01214469718
Domsense Srl                 http://www.domsense.com