[Erp5-dev] Experimental repository documentation structure

[Łukasz Nowak]

Hello,

Right now there is only two wikipages documenting experimental related
repository - one introduction[1] and one for erp5_forge_experimental
Business Template[2].

As more and more tools appears on this repository (and I really am
documentation freak ;) ) I'd like to propose documentation system for
those tools.

Structure might be quite simple:
* HowToUseExperimental - introduction about experimental with
disclaimers, only one listed on HowTo wikipage
and links to proper sections - might be merged/based/replace
ExperimentalRepository wikipage
* HowToUseExperimentalForge - documentation for erp5_forge_experimental
* HowToUseExperimentalCore - documentation for erp5_core_experimental
* HowToUseExperimentalProductExperimental - documentation for
Products/Experimental
* more HowTos for proper projects in experimental repository.

Projects owners/admins/developers/contributors shall be required to keep
up to date documentation. As editing wikipages is very easy not too much
additional work will be needed.

What do you think about proposed structure? Is it ok to update ERP5
wiki to such one?

And more - is it possible to add wikimacro, eg [[ExpDisc]], which will
show disclaimer about:
* how experimental is experimental
* that it is totally unsupported (by Nexedi, might even not be
supported by project owners, etc)
* use on your own risk, etc

Such way every HowToUseExperimental.* page would have this macro on top
to inform readers what is all about.

Regards,
Luke

[1] http://www.erp5.org/ExperimentalRepository
[2] http://www.erp5.org/HowToUseExperimentalForge

PS. What do you think about experimental forge documentation?[2] Is it
informative enough? I'd like to note, that time consumed on updating
such documentation is very, very short (read: cheap), I've got some
positive feedback, but I'd like to know your opinion.

[Rafael Monnerat]

I think that that experimental stuff is really great. In some cases we
can find some very interesting stuff in there. But I think that create
too much experimental stuff you can create some parts impossible to
maintain. IMHO, experimental code stuff should be reviewed and included
part by part in main code, of course if this case provides a good
behavior and tested.

Notes that some experimental code can propose a new design of one tool,
like a new production process or modules that use Linear Programming for
Optimize Sales (just one example). In these cases can be create a non
experimental stuff but some real bt5, like "erp5_another_trade" and
stored at some community repository. (I think NEXEDI can provide it as
experimental)

I'm not sure if was clear enough because my bad english, but I think
that the code and documentation should be centralized and merger as much
as possible, in order to not create unmaintainable parts used by unhappy
ERP5 clients :) .

Rafael Monnerat

Post by Łukasz Nowak
Hello,
Right now there is only two wikipages documenting experimental related
repository - one introduction[1] and one for erp5_forge_experimental
Business Template[2].
As more and more tools appears on this repository (and I really am
documentation freak ;) ) I'd like to propose documentation system for
those tools.
* HowToUseExperimental - introduction about experimental with
disclaimers, only one listed on HowTo wikipage
and links to proper sections - might be merged/based/replace
ExperimentalRepository wikipage
* HowToUseExperimentalForge - documentation for erp5_forge_experimental
* HowToUseExperimentalCore - documentation for erp5_core_experimental
* HowToUseExperimentalProductExperimental - documentation for
Products/Experimental
* more HowTos for proper projects in experimental repository.
Projects owners/admins/developers/contributors shall be required to keep
up to date documentation. As editing wikipages is very easy not too much
additional work will be needed.
What do you think about proposed structure? Is it ok to update ERP5
wiki to such one?
And more - is it possible to add wikimacro, eg [[ExpDisc]], which will
* how experimental is experimental
* that it is totally unsupported (by Nexedi, might even not be
supported by project owners, etc)
* use on your own risk, etc
Such way every HowToUseExperimental.* page would have this macro on top
to inform readers what is all about.
Regards,
Luke
[1] http://www.erp5.org/ExperimentalRepository
[2] http://www.erp5.org/HowToUseExperimentalForge
PS. What do you think about experimental forge documentation?[2] Is it
informative enough? I'd like to note, that time consumed on updating
such documentation is very, very short (read: cheap), I've got some
positive feedback, but I'd like to know your opinion.

[Łukasz Nowak]

Hello,

On 2008-03-19, 14:06:57

Post by Rafael Monnerat
I think that that experimental stuff is really great. In some cases
we can find some very interesting stuff in there. But I think that
create too much experimental stuff you can create some parts
impossible to maintain. IMHO, experimental code stuff should be
reviewed and included part by part in main code, of course if this
case provides a good behavior and tested.
Notes that some experimental code can propose a new design of one
tool, like a new production process or modules that use Linear
Programming for Optimize Sales (just one example). In these cases can
be create a non experimental stuff but some real bt5, like
"erp5_another_trade" and stored at some community repository. (I
think NEXEDI can provide it as experimental)
I'm not sure if was clear enough because my bad english, but I think
that the code and documentation should be centralized and merger as
much as possible, in order to not create unmaintainable parts used by
unhappy ERP5 clients :) .

I totally agree, that some parts of experimental shall be merged with
core, and than be removed from experimental.

But projects running by external developers without proper skills in
ERP5/Zope/etc (just like me), but connected with ERP5 are fitting
quite well into experimental. I doubt if they would be merged into ERP5
main repository in short time - those projects will live as long as they
will be *maintained* by external developers.

That's why I think that creating and providing documentation place for
such projects is important. I think that emphasise about not meeting
ERP5 quality of those projects would be enough informative for ERP5
clients/community/users/etc. And keep in mind, that many of
experimental projects might start as "external developer itch" - and
there might be no interest from ERP5 core maintainers to have them in
core system. And that's correct from open-source development view - but
why not provide platform for such people, do to collaborative work, and
integrate it a little - by common wikipages, mailing list, etc - with
ERP5?

Well - that's my personal opinion - as soon as experimental started and
I've got rw on this repository, I made decision to do some parts of my
work public in experimental. Tools I try to create aren't ideal, but I
hope, that as my skills in ERP5 will grow, some parts of my work
achieve "acceptable state to be reviewed" (not: merged!). And I do my
best to provide my work "usable" from beginning.

Regards,
Luke

[bartek]

Post by Rafael Monnerat
I think that that experimental stuff is really great. In some cases we
can find some very interesting stuff in there. But I think that create
too much experimental stuff you can create some parts impossible to
maintain.

True - there are monkey patches, and FS patches, and add-ons, and in
some cases we already run into problems with introducing new
experimental features because they touch a code which is already patched
by another experimental, and it is not possible to patch something
twice. Merging two experimentals into one would solve the problem, but
would also limit freedom to choose.

Post by Rafael Monnerat
IMHO, experimental code stuff should be reviewed and included
part by part in main code, of course if this case provides a good
behavior and tested.

Yes, this was actually the idea behind it. But it is up to the core
team, when and how are we going to do it.

Still, the more documentation the better, especially for experimentals.
Once a feature is merged, documentation for an experimental turns into a
documentation for the core. The big quesion here is, as Luke pointed
out, the structure: an experimental feature can be either something new
(like forge) - in this case it is clear that it should have its own
page. But if an experimental adds a functionality to something that
exists (e.g. listbox), or changes behaviour of something, should it be
documented separately, or within the page which documents the original
thing? This is the point where I'm not sure what to do.

Clearly there should be a page listing what's in there and how to install.

Post by Rafael Monnerat
Notes that some experimental code can propose a new design of one tool,
like a new production process or modules that use Linear Programming for
Optimize Sales (just one example). In these cases can be create a non
experimental stuff but some real bt5, like "erp5_another_trade" and
stored at some community repository. (I think NEXEDI can provide it as
experimental)
I'm not sure if was clear enough because my bad english, but I think
that the code and documentation should be centralized and merger as much
as possible, in order to not create unmaintainable parts used by unhappy
ERP5 clients :) .

There is NO SUCH THING ;)

Bartek

Post by Rafael Monnerat
Rafael Monnerat

Post by Łukasz Nowak
Hello,
Right now there is only two wikipages documenting experimental related
repository - one introduction[1] and one for erp5_forge_experimental
Business Template[2].
As more and more tools appears on this repository (and I really am
documentation freak ;) ) I'd like to propose documentation system for
those tools.
* HowToUseExperimental - introduction about experimental with
disclaimers, only one listed on HowTo wikipage
and links to proper sections - might be merged/based/replace
ExperimentalRepository wikipage
* HowToUseExperimentalForge - documentation for erp5_forge_experimental
* HowToUseExperimentalCore - documentation for erp5_core_experimental
* HowToUseExperimentalProductExperimental - documentation for
Products/Experimental
* more HowTos for proper projects in experimental repository.
Projects owners/admins/developers/contributors shall be required to keep
up to date documentation. As editing wikipages is very easy not too much
additional work will be needed.
What do you think about proposed structure? Is it ok to update ERP5
wiki to such one?
And more - is it possible to add wikimacro, eg [[ExpDisc]], which will
* how experimental is experimental
* that it is totally unsupported (by Nexedi, might even not be
supported by project owners, etc)
* use on your own risk, etc
Such way every HowToUseExperimental.* page would have this macro on top
to inform readers what is all about.
Regards,
Luke
[1] http://www.erp5.org/ExperimentalRepository
[2] http://www.erp5.org/HowToUseExperimentalForge
PS. What do you think about experimental forge documentation?[2] Is it
informative enough? I'd like to note, that time consumed on updating
such documentation is very, very short (read: cheap), I've got some
positive feedback, but I'd like to know your opinion.

_______________________________________________
Erp5-dev mailing list
Erp5-dev at erp5.org
http://mail.nexedi.com/mailman/listinfo/erp5-dev

[Jean-Paul Smets]

Hi,

I think it is a good idea for those who contributed to experimental that
they provide a bit of documentation about experimental ie.
- explain the purpose of experimental (please let me write a
guideline for this part, what you call HowToUseExperimentalForge)
- provide documentation for experimental stuff.

This structure (based on your suggestion):
- HowToUseExperimental (main page containing a list of
HowToUseExperimentalXXX)
- HowToUseExperimentalCore
- HowToUseExperimentalXXXX
is OK in my opinion

Each HowToUseExperimentalXXX should contain a link to the SVN repository.

About the content of experimental, it contains good things which will be
integrated to the core some day. It also contains some ad hoc solutions
which solve real problems in certain case but cause more trouble in
other cases. So, it is a good idea to warn users that they should not
rely on experimental and that using experimental could well lead to data
corruption (although it is not intended to).

Regards,

JPS.

Post by Łukasz Nowak
Hello,
Right now there is only two wikipages documenting experimental related
repository - one introduction[1] and one for erp5_forge_experimental
Business Template[2].
As more and more tools appears on this repository (and I really am
documentation freak ;) ) I'd like to propose documentation system for
those tools.
* HowToUseExperimental - introduction about experimental with
disclaimers, only one listed on HowTo wikipage
and links to proper sections - might be merged/based/replace
ExperimentalRepository wikipage
* HowToUseExperimentalForge - documentation for erp5_forge_experimental
* HowToUseExperimentalCore - documentation for erp5_core_experimental
* HowToUseExperimentalProductExperimental - documentation for
Products/Experimental
* more HowTos for proper projects in experimental repository.
Projects owners/admins/developers/contributors shall be required to keep
up to date documentation. As editing wikipages is very easy not too much
additional work will be needed.
What do you think about proposed structure? Is it ok to update ERP5
wiki to such one?
And more - is it possible to add wikimacro, eg [[ExpDisc]], which will
* how experimental is experimental
* that it is totally unsupported (by Nexedi, might even not be
supported by project owners, etc)
* use on your own risk, etc
Such way every HowToUseExperimental.* page would have this macro on top
to inform readers what is all about.
Regards,
Luke
[1] http://www.erp5.org/ExperimentalRepository
[2] http://www.erp5.org/HowToUseExperimentalForge
PS. What do you think about experimental forge documentation?[2] Is it
informative enough? I'd like to note, that time consumed on updating
such documentation is very, very short (read: cheap), I've got some
positive feedback, but I'd like to know your opinion.

[Łukasz Nowak]

Hello,

On 2008-03-20, 23:04:27

Post by Jean-Paul Smets
Hi,
I think it is a good idea for those who contributed to experimental
that they provide a bit of documentation about experimental ie.
- explain the purpose of experimental (please let me write a
guideline for this part, what you call HowToUseExperimentalForge)
- provide documentation for experimental stuff.
- HowToUseExperimental (main page containing a list of
HowToUseExperimentalXXX)
- HowToUseExperimentalCore
- HowToUseExperimentalXXXX
is OK in my opinion
Each HowToUseExperimentalXXX should contain a link to the SVN
repository.

So I'll prepare it.

I think about to merge http://www.erp5.org/ExperimentalRepository into
http://www.erp5.org/HowToUseExperimental , with redirect
ExperimentalRepository -> HowToUseExperimental . Is it ok?

Post by Jean-Paul Smets
About the content of experimental, it contains good things which will
be integrated to the core some day. It also contains some ad hoc
solutions which solve real problems in certain case but cause more
trouble in other cases. So, it is a good idea to warn users that they
should not rely on experimental and that using experimental could
well lead to data corruption (although it is not intended to).

It would be great if such disclaimer would be available as moin macro
and include it on *every* experimental related page. What do you think?

Regards,
Luke

[bartek]

Post by Jean-Paul Smets
Hi,
I think it is a good idea for those who contributed to experimental that
they provide a bit of documentation about experimental ie.
- explain the purpose of experimental (please let me write a
guideline for this part, what you call HowToUseExperimentalForge)
- provide documentation for experimental stuff.

Yes - already every patch in experimental repo contains a "preamble"
describing what it does, how to install it and a special section
labelled "RATIONALE" which explains why it's been done. I think we
should follow the same lines for bt5-s, though in case of the bt5-s the
wiki is probably a more suitable place.

Bartek

Post by Jean-Paul Smets
- HowToUseExperimental (main page containing a list of
HowToUseExperimentalXXX)
- HowToUseExperimentalCore
- HowToUseExperimentalXXXX
is OK in my opinion
Each HowToUseExperimentalXXX should contain a link to the SVN repository.
About the content of experimental, it contains good things which will be
integrated to the core some day. It also contains some ad hoc solutions
which solve real problems in certain case but cause more trouble in
other cases. So, it is a good idea to warn users that they should not
rely on experimental and that using experimental could well lead to data
corruption (although it is not intended to).
Regards,
JPS.

Post by Łukasz Nowak
Hello,
Right now there is only two wikipages documenting experimental related
repository - one introduction[1] and one for erp5_forge_experimental
Business Template[2].
As more and more tools appears on this repository (and I really am
documentation freak ;) ) I'd like to propose documentation system for
those tools.
* HowToUseExperimental - introduction about experimental with
disclaimers, only one listed on HowTo wikipage
and links to proper sections - might be merged/based/replace
ExperimentalRepository wikipage
* HowToUseExperimentalForge - documentation for erp5_forge_experimental
* HowToUseExperimentalCore - documentation for erp5_core_experimental
* HowToUseExperimentalProductExperimental - documentation for
Products/Experimental
* more HowTos for proper projects in experimental repository.
Projects owners/admins/developers/contributors shall be required to keep
up to date documentation. As editing wikipages is very easy not too much
additional work will be needed.
What do you think about proposed structure? Is it ok to update ERP5
wiki to such one?
And more - is it possible to add wikimacro, eg [[ExpDisc]], which will
* how experimental is experimental
* that it is totally unsupported (by Nexedi, might even not be
supported by project owners, etc)
* use on your own risk, etc
Such way every HowToUseExperimental.* page would have this macro on top
to inform readers what is all about.
Regards,
Luke
[1] http://www.erp5.org/ExperimentalRepository
[2] http://www.erp5.org/HowToUseExperimentalForge
PS. What do you think about experimental forge documentation?[2] Is it
informative enough? I'd like to note, that time consumed on updating
such documentation is very, very short (read: cheap), I've got some
positive feedback, but I'd like to know your opinion.

[Łukasz Nowak]

Hello,

On 2008-03-20, 23:04:27

Post by Jean-Paul Smets
Hi,
I think it is a good idea for those who contributed to experimental
that they provide a bit of documentation about experimental ie.
- explain the purpose of experimental (please let me write a
guideline for this part, what you call HowToUseExperimentalForge)
- provide documentation for experimental stuff.
- HowToUseExperimental (main page containing a list of
HowToUseExperimentalXXX)
- HowToUseExperimentalCore
- HowToUseExperimentalXXXX
is OK in my opinion

So be it. Done. ExperimentalRepository moved to HowToUseExperimental,
and only this is linked in HowTo list.

Post by Jean-Paul Smets
Each HowToUseExperimentalXXX should contain a link to the SVN
repository.

Done (for Forge).

Experimental contributors - please update wikipages content.

Regards,
Luke