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 > >
<<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