[Erp5-dev] Experimental repository documentation structure

[bartek]

Jean-Paul Smets wrote:
> 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

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