openerp-community team mailing list archive

[Pedro Manuel Baeza Romero <pedro.baeza@xxxxxxxxx>]

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