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

[Steve Swinsburg]

Any document will get out of date if people don't take the time to keep it current.

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

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.

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