[Erp5-dev] Experimental repository documentation structure

[bartek]

Rafael Monnerat wrote:
> 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.

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

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

> 
> Rafael Monnerat
> 
> 
> Łukasz Nowak wrote:
>> 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.
>>
> 
> _______________________________________________
> Erp5-dev mailing list
> Erp5-dev at erp5.org
> http://mail.nexedi.com/mailman/listinfo/erp5-dev


-- 
"feelings affect productivity. (...) unhappy people write worse 
software, and less of it."
Karl Fogel, "Producing Open Source Software"