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

[Steve Swinsburg]

Wasn't someone working on a database backed ServerConfigurationService where properties are stored in the DB rather than in the properties file? 

With the recent work around getting i18n strings in the DB, and coupled with some form of property registry, this sounds interesting. It may also give the added value of properties being editable live which would be sweet.

We still need good docs on them though so people can casually look them up.

cheers,
Steve

On 09/09/2010, at 11:36 PM, Noah Botimer wrote:

> Now, for something completely different...
> 
> I think all of our current forms of property documentation are pretty miserable. 
> 
> If we don't have interest or energy for a mechanism in the application itself for registering properties, then we should have one somewhere outside. We're using Drupal for sakaiproject.org, right? It's pretty easy to set up a little database with CRUD forms, searching, and sorting. Granted, we could do that anywhere, but it's a core feature of infrastructure we have. Registering properties with expected data type, recognized values, etc. would take us a long way. 
> 
> Having a curator is great, but I think we can get better about our process, and it should be more obvious and inclusive. If some random implementor finds that a property doesn't behave as expected, those docs should be editable. (The same should be true for translations.)
> 
> I would personally be interested in an application-internal registry and a bug-hunting mode of ServerConfigurationService where any property retrieved but not registered would throw errors at least to the logs. We would get good coverage with this turned on during a QA cycle.
> 
> Thanks,
> -Noah
> 
> On Sep 9, 2010, at 8:59 AM, csev <csev at umich.edu> 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