Just perfect Pedro, +1
On Tue, Mar 4, 2014 at 1:58 PM, Pedro Manuel Baeza Romero < pedro.ba...@gmail.com> wrote: > Hi all, > > I think we can split documentation in two parts: > > - One in the description of the module in RST format. We can add > images also if we want. This must be a description, long enough to > understand all what the module does, but brief enough to allow easy reading > of the purpose of the module. > - Then, we can expand this description using the trick of putting an > index.html file inside *static/description* folder with an extended > user manual, the same manner as this > module<https://www.openerp.com/apps/7.0/openeducat_erp/>. > For now, this information is only shown on Apps section of OpenERP or in > apps.openerp.com, but I can make a module that adds a tab to the > ir.module.module form for viewing this information. > > Next step would be to define templates for both sections. What do you > think about this proposal? > > Regards. > > > 2014-03-04 13:41 GMT+01:00 Joël Grand-Guillaume < > joel.grandguilla...@camptocamp.com>: > > 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 <j...@osbzr.com> 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 | j...@osbzr.com | 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.cau...@elico-corp.com>; >>> *Date: * Fri, Feb 28, 2014 07:24 AM >>> *To: * "openerp-community"<openerp-community@lists.launchpad.net>; >>> *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@lists.launchpad.net >>> 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 >> >> >> >> _______________________________________________ >> Mailing list: https://launchpad.net/~openerp-community >> Post to : openerp-community@lists.launchpad.net >> 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
<<inline: 2EE036E0@1CA95A61.D97C1153.jpg>>
_______________________________________________ Mailing list: https://launchpad.net/~openerp-community Post to : openerp-community@lists.launchpad.net Unsubscribe : https://launchpad.net/~openerp-community More help : https://help.launchpad.net/ListHelp