[Using Sakai] Using Sakai - Scheduling the January Call for Sakai Documentation Redesign project

[Sean Keesler]

One (long-term) issue with the current documentation process that some
schools have discussed is that it is hard to build a "local" version
of Sakai help/docs and maintain them over time. There isn't an easy
process for merging changes from the community docs into "my" local
(HTML) doc set. I think that this is due to the fact that the "single
source" of the docs is the XML docs in the IU KB...and not the docs
you get with the product download.

My understanding is that someone in the community pulls a snapshot of
Sakai docs from the IU KB with a REST call, runs some transformations
on it to build a set of web help files and checks it into svn for our
community version of contextual help bundled with the product. The
skill set needed to do that is scarce and the process is not well
known.

I've been wondering about the possibility of building a single source
"repository" of documentation that could be used as the "single
source" to build any number of derivative documentation sets. One way
to do this is to move towards an open standard for the source of the
documentation (such as DITA - http://dita.xml.org/) and use tools that
support the standard to develop a documented process for creating your
own set of docs.

On last month's call, the IU team mentioned that there was a long term
plan for IU to move their KB (and the Sakai KB articles) towards the
DITA standard. I wonder if there are other members of the community
with expertise in this area who would be interested in planning to
convert the current set of XML docs at IU to DITA.

Sean Keesler
130 Academy Street
Manlius, NY 13104
315-682-0830
sean.keesler at threecanoes.com



On Mon, Jan 10, 2011 at 9:39 PM, Regan, Alan <Alan.Regan at pepperdine.edu> wrote:
> Hi, John and Seth.
>
> Thank you for providing this information.  Given the timing of the 2.8 release, I can see how this documentation redesign project might not meet your deadlines right now.  That said, there's no time like the present to get started and plan for improvements moving forward.
>
> John, I very much like the notion of a central repository.  Although I missed the last conference call (I wasn't able to jump in until the very end), I believe there was a conversation about IU's knowledgebase.  Checking the Etherpad document, I see additional references to the IU KB.  I'd definitely like to learn more about this possibility for a community based KB.
>
> The next conference call on this topic will be next week -- Wednesday, January 19.  Tomorrow, I'll send out more details with time, phone number, etc.
>
> Thanks, all!
>
> Sincerely,
>
> Alan Regan, MFA
> Manager, Technology and Learning
> Information Technology
> Pepperdine University
> (310) 506-6756
>
>
> -----Original Message-----
> From: John Bush [mailto:john.bush at rsmart.com]
> Sent: Tuesday, January 04, 2011 9:38 AM
> To: Seth Theriault
> Cc: Regan, Alan; sakai-user at collab.sakaiproject.org
> Subject: Re: [Using Sakai] Using Sakai - Scheduling the January Call for Sakai Documentation Redesign project
>
> It might be a little late in the cycle to consider this for 2.8, but
> maybe for the future.  One of the things we do to separate the
> schedule of our release with the help content is to unhinge the help
> from the source and refer to the help externally.  I think this was a
> feature IU originally developed.  You can set a help location like
> this:
>
> help.location=http://myhelp.server.com/rsmart-help-content
>
> This allows us to push out help to all our clients without needing to
> rebuild/deploy each sakai instance.  It just needs a simple manifest
> xml file and the raw html content.  We use a word2doc converter to
> create all the html from a doc and then have a scripts that generates
> the manifest file.  There is a little manual editing to adjust the
> categorization and link the tool ids, but its pretty easy.
>
> There might be some benefit in the foundation following a similar
> model.  There's no reason why the help can't be dynamic as well.  You
> could create a community based knowledge base into the help and share
> it across all instances for example, even have it version aware like
> this:
>
> help.location=http://myhelp-sakai.server.com/help-content?version=280
> help.location=http://myhelp.sakai.com/help-content?version=281
>
> Something to consider...
>
> On Tue, Jan 4, 2011 at 10:10 AM, Seth Theriault <slt at columbia.edu> wrote:
>> Regan, Alan wrote:
>>
>>> Per Sean Keesler's notes, here is a proposed agenda:
>>>
>>> * Identify project lead to help with Sakai 2.8 coordination
>>>
>>> * Identify sections of the out of the box (OOTB) docs to target
>>>   for redesign in 2.8
>>
>> For these two items, time is of the essence. As I mentioned on
>> the call in December, any new or improved OOTB Help content for
>> 2.8 probably needs to be done and committed by mid-to-late
>> January to make the release.
>>
>> The release of Sakai 2.8 is scheduled for 1 March 2010:
>>
>> https://confluence.sakaiproject.org/display/REL/Sakai+2.8+Release+Schedule
>>
>> If you wait until the week of 17 January to act on these items,
>> it will probably be too late for anything to get into 2.8.
>>
>> Seth
>> _______________________________________________
>> sakai-user mailing list
>> sakai-user at collab.sakaiproject.org
>> http://collab.sakaiproject.org/mailman/listinfo/sakai-user
>>
>> TO UNSUBSCRIBE: send email to sakai-user-unsubscribe at collab.sakaiproject.org with a subject of "unsubscribe"
>>
>
>
>
> --
> John Bush
> 602-490-0470
> _______________________________________________
> sakai-user mailing list
> sakai-user at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai-user
>
> TO UNSUBSCRIBE: send email to sakai-user-unsubscribe at collab.sakaiproject.org with a subject of "unsubscribe"
>