openerp-community team mailing list archive

[Joël Grand-Guillaume <joel.grandguillaume@xxxxxxxxxxxxxx>]

Dear community,


If I may about this thread, I would prefer to have the documentation in the
__openerp__.py the way it is done for official one (in .rst).

Having it on an external wiki will be difficult to maintain within the
module evolution. Having a pdf is no good for the VCS (committing binaries)
and not easily readable within a review process.

Currently, during the review process, the reviewers can have a look on this
doc to better understand the module's purpose. They can ask directly to
adapt/improve it if not clear enough, etc...

Now I agree that a more "standard" format should be given to have something
homogeneous within the OCA, but for now, it seems the best option to me.

Regards,

Joël





On Sat, Mar 1, 2014 at 7:23 AM, jeff.wang <jeff@xxxxxxxxx> wrote:

> 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"
> <http://www.osbzr.com>
> 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 Caudal*CEO*--*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
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openerp-community
> Post to     : openerp-community@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openerp-community
> More help   : https://help.launchpad.net/ListHelp
>
>


-- 


*camptocamp*
INNOVATIVE SOLUTIONS
BY OPEN SOURCE EXPERTS

*Joël Grand-Guillaume*
Division Manager
Business Solutions

+41 21 619 10 28
www.camptocamp.com