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 _______________________________________________ Mailing list: https://launchpad.net/~openerp-expert-framework Post to : [email protected] Unsubscribe : https://launchpad.net/~openerp-expert-framework More help : https://help.launchpad.net/ListHelp
