[sakai2-tcc] Proposal: how to get rid of the properties documentation staleness in 2.8

[Beth Kirschner]

I would second Chuck's call for a single authoritative source of  
information. I would suggest that the default.sakai.properties file  
(sakai/config/configuration/bundles/src/bundle/org/sakaiproject/config/ 
bundle/default.sakai.properties) should be used to document all  
default values and the sakai/docs/sakai.properties file should be  
obsoleted (after comparing/merging documented defaults into the  
default file).

One problem with requiring developers to document their properties is  
that many/most do not have subversion access to either of the above  
files mentioned. I would suggest that anyone with commit rights to  
trunk should also be granted commit rights to the config directory.

- Beth

On Sep 9, 2010, at 8:59 AM, csev wrote:

> Perhaps the right thing to do is to move any useful material from  
> these pages to a single source for documentation and then delete  
> these obsolete pages or edit them to point to the real source of the  
> documentation about properties.
>
> We already carefully document the properties in the "kernel default"  
> properties file that Anthony carefully maintains.
>
> When a feature adds a property, we indicate this using the tic boxes  
> in the JIRA and as part of the processing of a completed JIRA,  
> Anthony carefully updates the properties file in SVN so we never get  
> out of sync.
>
> These confluence documents were labours of love by particular  
> individuals who now no longer maintain them - that is OK - it happens.
>
> Instead of adding work to keep 2-3 extra copies of this information  
> current - lets invest in improving the single authoritative source  
> of this information and then create multiple references to the  
> single authoritative reference.
>
> One of my favourite sayings is that Confluence is outstanding at  
> enabling the creation of lots of inaccurate documents very quickly.
>
> /Chuck
>
> On Sep 9, 2010, at 6:19 AM, Steve Swinsburg wrote:
>
>> This should also be kept current:
>> http://confluence.sakaiproject.org/display/DOC/Sakai+Properties+Reference
>>
>> Edit access is restricted so I add comments to the relevant pages  
>> when new ones come up.
>>
>> cheers,
>> Steve
>>
>>
>> On 09/09/2010, at 7:19 PM, Berg, Alan wrote:
>>
>>> I think this would save some emails to the dev list by confused  
>>> customers. I would enjoy a QA lead (problem owner) for this with a  
>>> Jira ticket to collect the found issues.
>>>
>>> Alan
>>>
>>> Alan Berg
>>> QA Director - The Sakai Foundation
>>>
>>> Senior Developer / Quality Assurance
>>> Group Education and Research Services
>>> Central Computer Services
>>> University of Amsterdam
>>>
>>> http://home.uva.nl/a.m.berg
>>>
>>> ________________________________________
>>> From: sakai2-tcc-bounces at collab.sakaiproject.org [sakai2-tcc-bounces at collab.sakaiproject.org 
>>> ] on behalf of Jean-Francois Leveque [jean-francois.leveque at upmc.fr]
>>> Sent: 09 September 2010 11:16
>>> To: sakai2-tcc at collab.sakaiproject.org
>>> Subject: [sakai2-tcc] Proposal: how to get rid of the properties  
>>> documentation staleness in 2.8
>>>
>>> Hi all,
>>>
>>> I'm afraid the current properties documentation is stale.
>>>
>>> Sometimes is even seems plain wrong.
>>>
>>> My proposal to solve this follows:
>>> 1) It should be clear that code owners (Leads, MT members, Kernel
>>> members) of each part of the code included in the Sakai release  
>>> should
>>> document each property their code is using. This includes both that
>>> their code is using the property and what the property does if  
>>> it's not
>>> properly documented.
>>> 2) Not documenting should be considered at least a major issue in  
>>> JIRA.
>>> 3) A review of the current state should be part of QA.
>>>
>>> I know it must be a burden for code owners in the current state of
>>> properties documentation, but this has to be at least started for  
>>> 2.8.
>>> Hope others may help them in this.
>>>
>>> Could involve myself in the review if we reach a consensus and  
>>> this is
>>> included in our 2.8 plans.
>>>
>>> What do you think?
>>>
>>> Cheers,
>>>
>>> J-F
>>> _______________________________________________
>>> sakai2-tcc mailing list
>>> sakai2-tcc at collab.sakaiproject.org
>>> http://collab.sakaiproject.org/mailman/listinfo/sakai2-tcc
>>> _______________________________________________
>>> sakai2-tcc mailing list
>>> sakai2-tcc at collab.sakaiproject.org
>>> http://collab.sakaiproject.org/mailman/listinfo/sakai2-tcc
>>
>> _______________________________________________
>> sakai2-tcc mailing list
>> sakai2-tcc at collab.sakaiproject.org
>> http://collab.sakaiproject.org/mailman/listinfo/sakai2-tcc
>>
>>
>
> _______________________________________________
> sakai2-tcc mailing list
> sakai2-tcc at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai2-tcc
>
>