[sakai2-tcc] Fwd: Sakai Documentation

[Seth Theriault]

FYI.

Begin forwarded message:

> From: markjnorton at earthlink.net
> Date: June 3, 2013 10:13:40 AM EDT
> To: Seth Theriault <slt at columbia.edu>, markjnorton at earthlink.net
> Subject: Sakai Documentation
> Reply-To: markjnorton at earthlink.net
> 

> As I mentioned in the meeting yesterday, I am interested in participating in a new effort to improve Sakai documentation. Let me warn you up front that my time to do this is VERY limited. Still, I have quite a bit of experience to share related to this effort.
> 
> Here are some of my initial thoughts:
> 
> Content matters much more than format. While eventually it would be nice to auto generate PDFs, web page set, etc., I think that getting the content together first is far more important. I would recommend a hierarchically organized set of web pages navigated by simple links, at first. Any number of tools support this kind of thing. Steer clear of settling on ANY tool at this stage. Write the web pages, check them into SVN or GIT. Though I'm not a big fan of GIT, it might actually be the better approach for documentation.
> 
> Start with an outline. Top level topics could include:
> About Sakai
> Installation
> Administration
> Setting Up a Course
> Setting Up a Profile
> Navigation (Basic Sakai User Docs)
> Sakai Tools
> I feel strongly that one person should be designated as the editor (project lead, whatever).  They should have a vision for the overall organization (something the wiki always lacked).  Drill down on topics and flesh out the outline.  Then, assign articles to volunteers to write.  Like Moodle, it makes sense to tie the doc set to a version (ie, 2.9.x, etc.).  If possible, writers of articles should includes notes of when a particular feature first appeared in Sakai (though this might be too much detail - its a judgement call).
> 
> A source management system should allow the entire doc set for a version to be downloaded at one.  Links should be relative, so that writers can navigate on their own, off line.  Thought should be given to accessibility, so follow WAI guidelines on the use of tags (headers, tables, images with alt, etc).  A general set of documentation guidelines will help the article writers, but it shouldn't be overly restrictive.  Use screen grabs to illustrate user interface descriptions, navigation, etc.  The default Sakai skin should be used for such illustrations.
> 
> I'm sure there's more, but that's all I can think of before breakfast.  Feel free to re-post this to TCC list or whatever list is appropriate to this new initiative.
> 
> - Mark Norton
> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai2-tcc/attachments/20130603/a7abc27b/attachment.html