[sakai2-tcc] Report from End-User Documentation Meeting

[Seth Theriault]

Hello,

Forgive the stream-of-consciousness feeling to this message.

Last Friday, I attended the initial meeting of a nascent 
Documentation group:

http://confluence.sakaiproject.org/display/ESUP/Help+Files+and+Documentation+Process+Redesign
http://confluence.sakaiproject.org/display/ESUP/2010-12-10+End-User+Documentation+Meeting

I really think documentation is an area where people can a 
serious contribution to Sakai that benefits everyone and gets 
them involved in the community. But, like many other things, it 
has never really gotten the global attention it deserves.

No more. The group that met on Friday seems to have lots of 
experience with end-user documentation -- they are writing it for 
their institutions or organizations -- but less with the 
technical aspects of how even the basic OOTB Help Tool content is 
served in Sakai.

For those that don't know, the bulk of the OOTB Help Tool content 
comes from a "Sakai instance" of the knowledge base maintained by 
Indiana University for its support purposes. Updates from the 
Sakai KB are brought into Subversion from time to time using 
scripts and other "magic" created by Stephen Marquard.

As described by the IU folks on the call, the quality of the KB 
content is variable: for example, if a document relates to 
functionality being used at Indiana, it might be better than for 
a tool that is not. People can submit comments, etc. but I am not 
sure how many do and everyone agrees that this isn't a 
sustainable way of updating the content. In addition, the KB 
items are not really versioned so Stephen has to tweak his 
scripts every time the version of the Sakai KB changes (usually 
when there is a new release). At the moment, the content going 
into the 2.7, 2.8, and trunk branches is the same.

As I said, the Documentation folks have a lot of experience. They 
also have lots of ideas about how to re-engineer the 
documentation process and delivery mechanism to better support 
collaborative work. I suggested to them that since time is short 
for the 2.8 release, they may want to pursue a short-term 
strategy to improve the existing OOTB help content, while 
pursuing any sweeping changes -- technical or otherwise -- for 
2.9 or so.

I also told them that they need to:

1) Appoint a fearless leader to interact with us, QA, RM, etc.
2) Be ready with 2.8 content changes by mid- to late-January

I think the TCC has a vested interest in seeing this group 
succeed for January and beyond.

Thoughts?

Seth