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

[Jean-Francois Leveque]

Had no technical solution in mind.

The information could be uploaded to confluence using an Excel file like 
Megan did not so long ago. This is not the kind of information we want 
to be edited in a wiki way, AFAICT.

Where else do we want to put this information and which format is needed.

Maybe the default config information could be included in the same 
source date.

Where else do we want information about the configuration properties?

Which kind of tabular input does work with confluence?

Should we do XML/XSL-T or something else?

J-F

csev a écrit :
> 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