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

[Anthony Whyte]

I recommend that we at a minimum:

1.  work to add all missing properties to the /config project's default.sakai.properties file (Beth, Chuck); retire sample.sakai.properties and docs/sakai.properties (Beth)
2.  given that many properties can be set in different and interesting ways (e.g., see SAK-18965) it may prove less than ideal to try to pack such explanatory text into a *.properties file (Noah); maintaining a second explanatory doc (as John Leasia used to do) may well continue to make sense.  That said, I prefer maintaining single files to sets of files.
3.  get a commitment from at least two people to work on updating and maintaining these files for 2.8 and also 2.7 according to an agreed upon format.
4.  treat a properties review like a conversion script review; it blocks the release until needed updates are added
5.  obtain a commitment from at least 2 individuals to take this work on for 2.8/2.7.
6.  ensure that committers have access to the files should be easy to arrange; besides svn-admins all MT members can commit to /config at present; adding others like the samigo team  can be done. 

As for "not too tough" an assignment--true enough I suppose but don't underestimate the time that it will take as well as the attention to detail required to update/correct these files. 

Anth


On Sep 9, 2010, at 10:07 AM, Noah Botimer wrote:

> OK, I'm sold. Using Drupal as a database is a bad idea for us. I think we have also been long agreed that single-source is the only sensible path (I would add multiple maintainer).
> 
> Files in SVN have some definite advantages. But comments in .properties is not the right format for authoritatively documenting .properties.
> 
> What I see as important:
> 
> * Differentiation based on release
> * Editing rights for the people who touch the code
> * Some simple format that is robust and easily checked/parsed
> * Some basic consistency of description, e.g., for data types/acceptable values, links to related JIRA tickets, etc.
> * Regular generation of web/text docs
> * Searchability/browsability on the web
> 
> Doesn't seem like this should be too tough...
> 
> Thanks,
> -Noah
> 
> On Sep 9, 2010, at 9:49 AM, csev wrote:
> 
>> Yikes!   
>> 
>> You are proposing going from 4 strange/unrelated/obsolete/inconsistent/manually maintained documents and moving to 5 and putting it in a database using software that may or may not be used as the content system for www.sp.org going forward.
>> 
>> Apache projects keep authoritative materials in SVN and give relevant people commit rights and then auto-generate HTML web sites for that SVN to make the materials more useful, searchable, readable, etc.
>> 
>> Your proposal is equivalent to suggesting that we document all our APIs in Drupal by pasting all the JavaDoc into Drupal and then having a JIRA each release titled "Drupal copies of JavaDoc are Out of Date".
>> 
>> One complete, carefully maintained, authoritative copy with multiple automated publishing options.
>> 
>> Now once we can auto-publish this material somewhere - it might be kind of cool to create a community based automatic patch/errata collector around the content that lets anyone in the community easily point out missing or incorrect information and provide fixes.  That is cool and value add beyond Apache.
>> 
>> Similarly we could do something to improve our ability to gather I18N input from the community as well.
>> 
>> Lets just avoid at all costs requiring multiple manual entry of the same information in several places. 
>> 
>> We also could improve the kind of documentation we include in SVN regarding properties so that auto-generated site is more useful.   If you note, I started my proposal with "take the good stuff from confluence".
>> 
>> /Chuck
>> 
>> On Sep 9, 2010, at 9:36 AM, 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
> 
> _______________________________________________
> sakai2-tcc mailing list
> sakai2-tcc at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai2-tcc
> 
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 3829 bytes
Desc: not available
Url : http://collab.sakaiproject.org/pipermail/sakai2-tcc/attachments/20100909/4381f9ae/attachment-0001.bin