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

[Beth Kirschner]

On Sep 9, 2010, at 9:33 AM, Steve Swinsburg wrote:

> Any document will get out of date if people don't take the time to  
> keep it current.
>
So true -- and it also helps to have someone take ownership of the  
document.

> This particular set of Confluence pages is an invaluable reference.  
> There are hundreds that are documented on those pages, but not in  
> any file in SVN I can see.
>
> Were you referring to the default.sakai.properties in the config  
> module?
> https://source.sakaiproject.org/svn/config/trunk/configuration/bundles/src/bundle/org/sakaiproject/config/bundle/default.sakai.properties
>
Yes

> I'd love to get edit details on those Confluence pages so I can keep  
> things current as I come across them. The reference goes back all  
> versions and is right there in one spot in an easy to read fashion.  
> It's fantastic.
>
> It's a sad state of affairs if we have to point someone to a file in  
> SVN to get documentation. Project teams need to keep their  
> documentation current, and we need to be able to make that  
> information readily accessible.
>
I agree, but I'm not sure about trying to keep two files up-to-date  
and in sync. It would be nice if someone could put together some sort  
of javadocs-like script that would read the default.sakai.properties  
file and generate a nice HTML page documenting the properties.

- Beth

> cheers,
> Steve
>
>
> On 09/09/2010, at 10:59 PM, 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
>
> _______________________________________________
> sakai2-tcc mailing list
> sakai2-tcc at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai2-tcc
>
>