openerp-community team mailing list archive

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

Just perfect Pedro,

+1


On Tue, Mar 4, 2014 at 1:58 PM, Pedro Manuel Baeza Romero <
pedro.baeza@xxxxxxxxx> 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.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
>>
>>
>


-- 


*camptocamp*
INNOVATIVE SOLUTIONS
BY OPEN SOURCE EXPERTS

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

+41 21 619 10 28
www.camptocamp.com