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

Thu Sep 9 06:49:48 PDT 2010

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