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

[Noah Botimer]

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