[Using Sakai] End-User Documentation

[Marshall Feldman]

Dear Mr. Smart,

I looked at your documentation, and it's pretty good. Still it doesn't 
provide the detailed, technical answers to the sorts of questions I 
posed: what are the specs for the csv fields to be imported into the 
Schedule tool (your docs only talk about importing from Outlook and 
don't describe the fields; what if someone is importing from Thunderbird 
or writing their own program in C++ and just want to export to Sakai?), 
are keywords case-sensitive and how are they delimited, etc.

I'm not singling out your documentation. It's better than much that's 
out there. However, it's still typical in that detailed, authoritative 
technical specs are largely absent. I'm posting this because I'd like to 
see this conversation shift from "Where should we store end-user 
documentation and how should we write it?" to "What should end-user 
documentation include and who should write it?"

In one of the other posts on this subject, someone suggested moving the 
"technical" information somewhere else, implying end-users don't need 
"technical" information. Well maybe they don't need documentation on how 
to install Sakai, but why wouldn't then need very technical 
documentation for other things?

Some time during the 1980s, software went from being geared primarily 
for technical users and shifted to a mass consumer market. Instead of 
engineers, software was now targeting secretaries and sales people. 
Despite the fact that this list is called "Sakai-user," most of the 
participants seem to be Sakai administrators and support staff. Maybe 
end users don't participate more because they fall at the low, 
consumer-end of the spectrum. I don't know, but a large segment of most 
universities' faculties and student bodies are very technically 
sophisticated, dare I say more than many Sakai administrators and 
support staff. So why does almost all Sakai documentation read like a 
"getting started" section in an introductory tutorial for Microsoft Word 
rather than the OpenOffice Developer's Guide (which, despite its name, 
provides guidance for Basic, Java, and C++ programmers writing software 
to interface with the OO API)?

If an end user wanted to user their own css file to give a Sakai course 
site a certain look and feel, where would they look to find out how?

     Marsh Feldman

On 9/29/10 [Sep 29, 10] 5:08 PM, 
sakai-user-request at collab.sakaiproject.org wrote:
> Message: 1
> Date: Wed, 29 Sep 2010 15:42:17 -0500
> From: "Smart, Whitten J"<ws15 at txstate.edu>
> Subject: Re: [Using Sakai] sakai-user Digest, Vol 19, Issue 31
> To:"sakai-user at collab.sakaiproject.org"
> 	<sakai-user at collab.sakaiproject.org>
> Message-ID:
> 	<542D8F577CC93241929A7E07F147CDE20326BEE6B3 at BOBCATMAIL1.matrix.txstate.edu>
> 	
> Content-Type: text/plain; charset="us-ascii"
>
> We at Texas State have developed our own customized documentation, videos, FAQ, and searchable knowledgebase (the "how do I" questions) for both faculty and student users.  All of our information can be found athttp://tracsfacts.its.txstate.edu
>
>
> Regards,
>
> Whitten Smart
> User Services Consultant II
> ETC Support
> Texas State University - San Marcos
>