[Erp5-dev] Experimental repository documentation structure

[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.
      

Łukasz Nowak a écrit :
> 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.
>
>   


-- 
Jean-Paul Smets-Solanes, Nexedi CEO - Tel. +33(0)6 62 05 76 14
ERP5 Enterprise: Free / Open Source ERP for Critical Applications
http://www.erp5.com
ERP5 Express: Hosted Open Source ERP for small companies
http://www.myerp5.com
Nexedi: Consulting and Development of Free / Open Source Software 
http://www.nexedi.com