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 <mailto:rvalyi@xxxxxxxxx>>:
On Tue, Mar 4, 2014 at 2:38 PM, Pedro Manuel Baeza Romero
<pedro.baeza@xxxxxxxxx <mailto: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
<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_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/#%21/rvalyi>
+55 21 2516 2954
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
