openerp-community team mailing list archive

[Eric Geens <ericgeens@xxxxxxxxx>]

As a non-technical newcomer to OpenERP, I really applaud these kind of
initiatives. Maybe it is a stupid remark (and you can shoot me for this) but
one of the arguments I used to give to all potential prospects looking at an
Open Source project (vs. traditional ERP vendors), was that it lacked
maturity in documenting solutions (and an unpredictable roadmap along with
it). Documenting and streamlining the process of it is a good step towards
building credibility with end-users. Explaining how a module behaves has
direct visibility towards end-users, and I must admit that it adds
seriousness, maturity and  „structure" to the way Open Source (and OpenERP)
is being organized.
I would be happy to contribute to exactly do the stuff coders hate… In my
belief it is essential that things are being well defined and documented.
Being a linguist (originally) I would love to do the „explanations and
exemples” on the solutions proposed…

Kind regards,
Eric


From:  Pedro Manuel Baeza Romero <pedro.baeza@xxxxxxxxx>
Date:  dinsdag 4 maart 2014 20:32
To:  "jeff.wang" <jeff@xxxxxxxxx>
Cc:  "openerp-community@lists.launchpa"
<openerp-community@xxxxxxxxxxxxxxxxxxx>
Subject:  Re: [Openerp-community] About description and manual files
forOCAmodules

Hi, Jeff,

I understand that non technical persons hate to write in a strange
semi-programming language, but this is not the case with RST: syntax is
pretty straight-forward. You can even split the process in two: functional
experts write user manual in plain text and capture snapshots, and a
developer, taking very little time, apply RST format.

We need to balance easy of making with possibilities of integration and
automation, and I think Raphäel proposal makes this.

Regards.


2014-03-04 20:16 GMT+01:00 jeff.wang <jeff@xxxxxxxxx>:
> Hi gurus,
> 
>    Please do think about who will be the author and entertainer of these .rst
> files, maybe developer only. think about how many work will need to be done by
> developer before commit module to community project, additional  CRAZY hurry
> OpenERP core version change...
> 
>    Too much work for developer, too few chance for a non-technical person(we
> call them function expert) involve.
> 
>    My suggestion: code for developer, write by developer, review by developer.
> use a tool they like.
>                          doc for consultant, write by consultant(init by
> developer is ok), review by consultant. use a tool they like.
> 
>     As a developer, I hate writing document, and I even hate other developer
> don't write document.
> 
>    BUT it is life.
> 
> ------------------
> Jeff Wang |  jeff@xxxxxxxxx | 18016291663 <tel:18016291663>  | 02158980787
> @OpenERP_Jeff "As simple as possible, As complex as needed"
>     <http://www.osbzr.com>
>  Maintainer of Open ERP china community
>  http://www.openerp-china.org
>  
> 
> 
> ------------------ Original ------------------
> From:  "Raphael Valyi";<rvalyi@xxxxxxxxx>;
> Date:  Wed, Mar 5, 2014 02:50 AM
> To:  "Pedro Manuel Baeza Romero"<pedro.baeza@xxxxxxxxx>;
> Cc:  
> "openerp-community@lists.launchpa"<openerp-community@xxxxxxxxxxxxxxxxxxx>;
> Subject:  Re: [Openerp-community] About description and manual files
> forOCAmodules
> 
> On Tue, Mar 4, 2014 at 2:38 PM, Pedro Manuel Baeza Romero
> <pedro.baeza@xxxxxxxxx> wrote:
>> Hi, Raphäel,
>>  
>> In this MP, Stefan has embedded an image in the description:
>> 
>> http://bazaar.launchpad.net/~therp-nl/account-financial-tools/7.0-add_move_li
>> ne_no_default_search_period_journal/view/head:/account_move_line_no_default_s
>> earch/__openerp__.py#L35
>> <http://bazaar.launchpad.net/%7Etherp-nl/account-financial-tools/7.0-add_move
>> _line_no_default_search_period_journal/view/head:/account_move_line_no_defaul
>> t_search/__openerp__.py#L35>
>> 
>> So, there's a way to do it.
> 
> Thank your Pedro! I was probably using the wrong path before.
> 
> Then I make the following proposal:
> 
> a module could have README.rst root file. This README..rst file could then be
> included into __openerp__.py using an rst include macro such as with the image
> example you just pointed.
> 
> Hence if the module is hosted on Github for instance, the module description
> is straightforward, right on the project page, just the projects where the
> wiki entry page is a README.md file. No fluff so we don't create too much
> dependencies on specific module stores.
> 
> example: the request Python HTTP client:
> https://github.com/kennethreitz/requests
> 
> Then, we could use the docutils command (or a dedicated wrapper eventually;
> docutils supports it well) to automatically convert this README.md into an
> HTML static/description file (such as
> https://www.openerp.com/apps/7.0/openeducat_erp/ ) that would be beginner and
> apps friendly, possibly using an OCA HTML template.
> 
> 
> So this is close to Pedro suggestion, but the idea is this way the
> documentation is primarily in all the rst format, that mean it's not lost, we
> can work on it, just as if it where code. We also put the content in a root
> REAMDE.rst rather than __openerp__.py itself so just browsing the folder
> brings the documentation without depending on a python runtime to extract it
> from __openerp__.py
> 
> Eventually the documentation is not just one single REAMDE.rst file but a
> collection of several files (possibly in a docs folder) and only the minimal
> presentation file could be included i the __openerp__.py file.
> 
> so the module I propose would be:
> 
> module
>     view
>     model
>     security
>     tests
>     data
>     i18n
>     docs #rst to be icluded or linked in the README, Sphinx doc...
>     static
>         description #generated
>         images
>     __openerp__.py #includes the README rst, or some summary file from docs if
> the README is too large
>     README.rst #primary documentation, possibly including subfiles from the
> doc folder
> 
> 
> Do I miss something?
> Thoughts?
> 
> -- 
> Raphaël Valyi
> Founder and consultant
> http://twitter.com/rvalyi <http://twitter.com/#!/rvalyi>
> +55 21 2516 2954 <tel:%2B55%2021%202516%202954>
> www.akretion.com <http://www.akretion.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