Re: [Openerp-community] About description and manual files forOCAmodules
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 Date: dinsdag 4 maart 2014 20:32 To: "jeff.wang" Cc: "openerp-community@lists.launchpa" 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 : > 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 | j...@osbzr.com | 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";; > Date: Wed, Mar 5, 2014 02:50 AM > To: "Pedro Manuel Baeza Romero"; > Cc: > "openerp-community@lists.launchpa"; > Subject: Re: [Openerp-community] About description and manual files > forOCAmodules > > On Tue, Mar 4, 2014 at 2:38 PM, Pedro Manuel Baeza Romero > 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
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 : > 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 | j...@osbzr.com | 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";; > *Date: * Wed, Mar 5, 2014 02:50 AM > *To: * "Pedro Manuel Baeza Romero"; > *Cc: * "openerp-community@lists.launchpa"< > openerp-community@lists.launchpad.net>; > *Subject: * Re: [Openerp-community] About description and manual files > forOCAmodules > > On Tue, Mar 4, 2014 at 2:38 PM, Pedro Manuel Baeza Romero < > pedro.ba...@gmail.com> 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_line_no_default_search_period_journal/view/head:/account_move_line_no_default_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 > www.akretion.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
Re: [Openerp-community] About description and manual files forOCAmodules
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 | j...@osbzr.com | 18016291663 | 02158980787 @OpenERP_Jeff "As simple as possible, As complex as needed" Maintainer of Open ERP china community http://www.openerp-china.org -- Original -- From: "Raphael Valyi";; Date: Wed, Mar 5, 2014 02:50 AM To: "Pedro Manuel Baeza Romero"; Cc: "openerp-community@lists.launchpa"; Subject: Re: [Openerp-community] About description and manual files forOCAmodules On Tue, Mar 4, 2014 at 2:38 PM, Pedro Manuel Baeza Romero 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_line_no_default_search_period_journal/view/head:/account_move_line_no_default_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 +55 21 2516 2954 www.akretion.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
