openerp-community team mailing list archive

[Daniel Reis <dgreis@xxxxxxx>]

I think Jeff's point was for users to be able to access contextual help
from the screen they are currently at.
  It's a feature on any decent ERP that is missing from ERP. It is
particularly valuable for functional experts, that depend on this to
figure out the impact of configuration decisions (in closed source you
can't ask a technical expert to look into the code ;-)

  But it's also interesting for this documentation system to be able to
support customer-specific processes documentation.
  Part of their service Integrator could provide customers online
contextual documentation on their specific processes.
  In the light of a Management System (such as ISO9001), it could even
mean support the system's documentation, accessible in context with user's
actions.

  I would say such a contextual documentation system would have to meet
these requirements:

  1) A User should be able to access a documentation page specific for the
screen he is at.
  2) The Documentation should reflect the modules / features actually
installed / available in the system.
  3) The Documentation should be translatable.
  4) The Documentation should easily editable by non-technical users.

  Making an imagination exercise, picture yourself at the Partners form.
  - You should press "F1" or click on a [?] button and a documentation
page on Partners would pop-up.
  - It would feature an initial generic text (probably from the standard
module) and a list with all fields with a detailed explanation for each
one.
  - Also each button would be listed accompanied with an explanation.
  - Additional sections would also be there to detail specific features,
such as those added by additional modules installed.

  From the above, I derive that:
  - The Documentation should be installed in modules, so that we can meet
#2. (Jeff, I think this rules out the external wiki solution).
  - The Documentation should use the current OpenERP translations system
  - The Documentation should be able to use inheritance, much like what
happens with views.

  Right now I can see a couple of implementation strategies to meet these
requirements.
  But It would be nice to see other opinions on this approach first.

   Regards
   /DR
 

Quoting Raphael Valyi <rvalyi@xxxxxxxxx>:
> 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_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[1]
> +55 21 2516 2954
> www.akretion.com[2]
>
>  




Ligações:
---------
[1] <a href="http://twitter.com/#!/rvalyi";> http://twitter.com/#!/rvalyi</a>
[2] <a href="http://www.akretion.com/";> http://www.akretion.com/</a>