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.
