openerp-community team mailing list archive

["jeff.wang" <jeff@xxxxxxxxx>]

Hi Eric and ALL,


    Thank you for start this interesting thread.


   We know there is a field named "website" in the description file for each module, mostly developer fill in this field follow OPENERP SA way with the website of author's home page, for me this is not the best way.  


   I assume everybody here agree that OpenERP's main bottleneck is the lack of documentation on detail enough.  Many ERP product support F1 help on the user interface lead the end user to a help page with context, describe what is the meaning of each field on the screen He/She is viewing.  For OpenERP, we are very surprised that that the HELP button is only in the DEBUG MODE (also the "set default" button , this is another story  ), maybe this is because each time we click it when OpenERP5.0 and OpenERP6.0, it lead us to some page on doc.openerp.com,  but this is a book,   It's is not detail to field level in the most case. that's way End User disappointed on document and keep asking same entry level question to expert.   Same situation happen when somebody(ERP manager in Client or Consultant from firm) download a module from apps.openerp.com, we know most developer is not good at writing good enough description in the __openerp__.py (at least when they publish them), and we can sure doc.openerp.com will never cover all the detail for community modules, so this will be continuously issue an grow very fast thank to more and more module been published by community members.


   My solution is, OCA should setup a WIKI website (I personal preffer LIONWIKI - http://lionwiki.0o.cz/index.php?page=Main+page ), with this wiki we can create a page for each OpenERP module ( From any author) , then put this page's link in the website field of __openerp__.py in your module. then before install the module, man can click this link and see more maintainable wiki page with:


- Summary
- Objective of the module
- Main functionality or process
- Limitations and TODO
- Log changes


- author link with BIG company LOGO
- source code repo link
- related blog or video link
- Everything somebody want to share base on this module
- Better with a Vote for this page, Comments from end user


Wiki is a way collaboration write document like we did for open source software, I am sure everybody in open source world like this way, better than make a merge request to fix a typo in __openerp__.py


Even more, we can create page for model, eg, page=stock.move, and list all field on the screen( even some field hidden) and describe what value should be input cause what result.


I have tried to write a module to add a Blue help button on each openerp page and lead user to the wiki page for his opening interface. 


Be aware that this wiki is NOT replace openerp books, for book is used to tell a story for a entry level user to buy in the software, wiki is used to write a dictionary to reference in our blueprint process.


I do have a wiki http://www.osbzr.com/help.php for CHINESE only, you can look this as a POC, please ignore the AD and LOGO if these make you unhappy.
   
Looking for further discussion on this!
------------------
Jeff Wang |  jeff@xxxxxxxxx | 18016291663 |02158980787
@OpenERP_Jeff "As simple as possible, As complex asneeded"

Maintainer of Open ERP china community 
http://www.openerp-china.org


 




------------------ Original ------------------
From:  "Eric Caudal";<eric.caudal@xxxxxxxxxxxxxx>;
Date:  Fri, Feb 28, 2014 07:24 AM
To:  "openerp-community"<openerp-community@xxxxxxxxxxxxxxxxxxx>; 

Subject:  [Openerp-community] About description and manual files for OCAmodules



Hi,
There is a policy to cleanse description files for modules that arehosted in the community association (take out advertisement orexternal links).

What about we create a common and standardized description file forthe hosted modules reminding:
- "This is a module from the OCA..."
- OCA webpage
- How to post a bug or enhancement request
- Any other useful information (dependency and contributor's listshould be already somewhere else though)
- any link to available resource (video, blog, docs...)
- Of course the description of the modules.

For the description of the modules, is there any guideline so farfor content?
I would think of a short content:
- Summary
- Objective of the module
- Main functionality or process
- Limitations and TODO
- Log changes

Somehow, I think every module should have a "doc" folder with aname_of_the_module_manual_en.pdf or name_of_the_module_manual_en.mdinside (probably better pdf to be able to have screenshot and easyprinting).
There should be at least one use case described in the manual withoptions for others.

Organizing the information like the current OpenERP doc launchpadwould allow to have a central place to do that and a commonprocedure for printing each manual, altogether or one by one.

Any opinion?
--
Eric CaudalCEO--Elico Corporation, Shanghai branchOpenERP Premium Certified Training Partner Cell: + 86 186 2136 1670Office: + 86 21 6211 8017/27/37Skype: elico.corperic.caudal@elico-corp.comhttp://www.elico-corp.com