openerp-community team mailing list archive

[Alejandro Santana <alejandrosantana@xxxxxxxxx>]

+1 to RST in manifest (nice for review and techies) and html within the
module (for deeper explanation and for end users), as proposed by Pedro.

Alejandro Santana
alejandrosantana@xxxxxxxxx
~
ANUBÍA, soluciones en la nube, S.L.
www.anubia.es
 El 04/03/2014 17:56, "Eric Caudal" <eric.caudal@xxxxxxxxxxxxxx> escribió:

>  My concern here is the non-techie end user will not have the tools to
> read an rst file (I understand it is powerful but it is not user-friendly
> for non technical audience).
>
> Now the html seems to me a great idea (better than pdf indeed and with a
> usage as widely spread).
> Having it in the module section is a must.
>
>
>  Eric Caudal*CEO*
> --*Elico Corporation, Shanghai branch
> OpenERP Premium Certified Training Partner *
> Cell: + 86 186 2136 1670
> Office: + 86 21 6211 8017/27/37
> Skype: elico.corperic.caudal@elico-corp.comhttp://www.elico-corp.com
>
> [image: Elico Corp]
> On 03/04/2014 08:59 PM, Joël Grand-Guillaume wrote:
>
> 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
>
>
>
> _______________________________________________
> 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
>
>
>
> _______________________________________________
> 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
>
>