Overview

The Documentation Working Group has identified four major areas of focus. We will need project leads for each area.

2011-2012 Lead(s): Rebecca Darling, Alan Regan
2010-2011 Lead(s): Mathieu Plourde, Alan Regan, Elizabeth Venstra

Focus: Content

Short description: Review and revise the built-in help documentation within the existing tool. Look at text for accuracy and completeness, review layout and formatting, and keep the end-user in mind.

Scope: Limited to tool-based, how-to documentation at this time.

Current Project Page: Help Files 2.9 Content Project
Past Project Page: Help Files 2.8 Project Home

Lead(s): TBD

Focus: Technical

Short description: Review how institutions can easily export and customize the existing help content for their unique communities. Investigate what changes can be made to the coding of the existing help pages to enable rebranding options. Discover tools or methods to extract the content and produce customized output for institutions that adopt Sakai.

Scope: TBD

Project Page: Help Files Local Customization Project

Lead(s): TBD

Focus: Technical

Short description: Review the needs of the community to develop an improved help tool within Sakai. Discover and define the features and capabilities that will enable end-users to quickly search for and use relevant help information.

Scope: TBD

Project Page: TBD

Lead(s): TBD

Focus: Content/Technical

Short description: Assist the community in identifying partners or tools to provide multiple language support for the built-in help files of Sakai.

Scope: TBD

Project Page: TBD

https://sas.elluminate.com/m.jnlp?password=M.8BD62DED7684B09FFA8A85473A0039&sid=2009099

It has now become clear that the Sakai out of the box (OOTB) help files are suffering from a lack of attention. This everlasting issue has been lingering for the longest while, with bursts of interest occurring here and there, as the following links demonstrate (this list is incomplete, please add yours):

It is now time to gather members of the Sakai community and Foundation to tackle this problem once and for all. Bad documentation leads to unnecessary local efforts that do not find their way back to the OOTB help files. Now that so many schools are looking at LMS alternatives, and that the Sakai community wants to promote the use of Sakai, this is a blocker to adoption for many.

Recent threads on the "Sakai User" list has generated interest in this process. It's now time to walk the talk.

Note: Discussion on this topic occurs primarily on the documentation@collab.sakaiproject.org mailing list. To subscribe, go here: [http://collab.sakaiproject.org/mailman/listinfo/documentation]

Who's Interested?

Name

Email

Institution

Expected contribution

Alan Regan

alan dot regan at pepperdine dot edu

Pepperdine University

Ideas, workflows, content (Needs Assessment/Ideas, Standards, Editorial Board, Writing)

Lorie Stolarchuk

lorie@uwindsor.ca

University of Windsor

Pain points of current situation, integration joys/woes of Brock's MediaWiki, ideas (time permitting )

Robin Hill

hill@uwyo.edu

University of Wyoming

Content, editing... whatever I checked on Alan Regan's form (Standards, Editorial Board, Writing)

Sean Keesler

sean.keesler@threecanoes.com

Three Canoes

Project Management, Writing, Workflows, Editing

Matt Clare

Matt.Clare@BrockU.ca

Brock University

We're more than happy to share our documentation at http://kumu.brocku.ca/sakai A lot of MediaWiki experience. Big advocate of ease-of-edit and radical trust.

Greg Doyle

 

University of Cape Town

Writing

Margaret Wagner

mwagner@umich.edu

University of Michigan

Ideas, Writing

Trisha Gordon

psg3a@virginia.edu

University of Virginia

Content, editing, ideas

Kara Stiles

kstiles@rsmart.com

rSmart

Content, Writing

Rafael Morales

rmorales@udgvirtual.udgd.mx

University of Guadalajara

Localization

Adam Marshall

adam dot marshall at ox.ac.uk

Oxford uni

content (& video scripts)

Matt Schneider

matt.schneider@jhu.edu

Johns Hopkins University

Content creation, Editing, ideas

Whitten Smart

ws15@txstate.edu

Texas State University - San Marcos

Ideas, Writing, Editing

Amber D. Evans

adevans@vt.edu

Virginia Tech

Ideas, workflows, leadership (Needs Assessment/Ideas, Editorial Board), CONTENT/WRITING, Styleguides/Standards (templates, XML, etc.).  I developed all of the customized documents (many for more advanced Sakai users) on the OLCS web site at http://www.olcs.lt.vt.edu/scholar/scholarHandoutsAutoIndexer.html

Jon Hays

jonmhays@media.berkeley.edu

UC Berkeley

Ideas, content, accessibility

Clay Fenlason

clay.fenlason@et.gatech.edu

Georgia Tech

Content, editing, Sakai OAE

Jeff Ziegler

ziegler@umich.edu

University of Michigan

Workflows, Writing, Editorial Board, Needs Assessment/Ideas

Sonette Yzelle

syzelle@unisa.ac.za

University of South Africa

Ideas, writing & editing

Barb Kerns

brk@bradley.edu

Bradley University

Writing, Editing.  We have a custom documentation site (in Drupal) at http://sakaihelp.bradley.edu.

Kerrie Stephenson

kerrie.stephenson@hull.ac.uk

Hull University

Ideas, writing, editing

Patrick Lynch

p.lynch@hull.ac.uk

Hull University

Ideas, writing, editing

Kim Eke

kim_eke@unc.edu

University of North Carolina at Chapel Hill

Ideas, writing, editing

Some areas of contribution to consider: Project Management, Needs Assessment/Ideas, Accessibility, Standards, Editorial Board, Writing, Programming/Development, Workflows, Localization (Internationalization/Translation), Screenshots/Videos.

Key Questions

Before we start defining our process, please share your thoughts the following questions:

1. How do we define "end-user documentation" - purpose, audience, and content? And media?

2. What do users need to accomplish their tasks in Sakai?

3. How do users find support when they hit the wall?

4. What works in the way our documentation is organized?

5. How should the help documentation be organized?

6. What is the current process used to revise and improve the OOTB documentation?

7. What are the difference between help files and other documentation?

8. How can we encourage the Sakai community to contribute their improvement back to the OOTB help files?

9. How should we vet the quality of the OOTB help files?

Collaborative review and verification-- inconveniently tedious and time-consuming, and dependent on careful coordination-- with the same level of respect and attention accorded to QA of code.

10. How should we address the branding, customization, and localization issues (different names, logos, style sheets, languages, policies)?

11. "Wish list" thoughts?

NOTE: Improvements to the design of the learning environment (many of which are planned in S3) will also go a long way in improving the ease and usability of the service. Providing mouse-hover tool tips and other prompts will offer "just-in-time" support on the page. Of course, this will not eliminate the need for helpful built-in documentation and other support pages.

12.  What is the current status of Sakai documentation?

Study of Samigo, at Stanford-- Documentation of Tests & Quizzes

A. Source Code
Original code written by programmers long gone, so some inline comments are out-of-date, but remain because the new developers didn't bother to remove them and in case they provided some history behind the code. New inline comments are added by current developers.
B. Functional Specs on Confluence
Lydia Li and the other developers (Karen Tsao takes care of Samigo), maintain the "Project: Samigo" web pages, with systematic updates on every new release.  The Academic Computing group is not aware of any formal Sakai requirement.
This compares favorably with most other Projects' pages.  Some Project pages on Confluence show no activity since 2.5, some still active, some dormant since 2006 or 2007.
C. User Docs for Instructors and Students

For developers and deployers:

A case study:  Why is it so hard to document the portfolio tools?  (R. Hill, relying on S. Keesler)

  1. Because we're too lazy to learn the skills clearly designated as necessary; we want documentation to reveal the effort-free path.
  2. Because the Help files are written to an audience, trained faculty, that enjoys an environment of expert support.
  3. Because Sean's comprehensive documents on Confluence are found in different branches of the hierarchy.
  4. Because some Confluence pages have lost their context and suffer from neglect, e.g., http://confluence.sakaiproject.org/display/OSPDOC/Data+warehouse
  5. Because there is no visible intermediate result that affords the author a self-check of progress.
  6. Because there are assumed procedures and scenarios that hide restrictions.
  7. Because portfolios, insofar as they capture the essence of learning, are inherently complex objects.