Page Comparison

...

Overview

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

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):

• Sakai Community Documentation (Denver, 2010): http://confluence.sakaiproject.org/display/CONF2010/Sakai+Community+Documentation
• Strategies to Support Your Users: Custom Documentation and Help Files (Boston, 2009): http://confluence.sakaiproject.org/display/CONF10/Thursday-Strategies+to+Support+Your+Users
• BOF about community documentation (Boston, 2009): http://confluence.sakaiproject.org/display/CONF10/Thursday-Documentation-Discussing+a+Better+Sharing+Strategy+%28BOF%29
• Toward a Sakai Documentation Project (2008): http://confluence.sakaiproject.org/display/DOC/Toward+a+Sakai+Documentation+Project
• Documentation Standards: http://confluence.sakaiproject.org/display/DOC/Documentation Standards
• The End-User Support pages: http://confluence.sakaiproject.org/display/ESUP/End-User+Support+Group
• The Project: Help pages:  http://confluence.sakaiproject.org/display/HELP/Home
• Terminology: http://confluence.sakaiproject.org/display/ESUP/Terminology
• Motivating Issues: http://confluence.sakaiproject.org/display/ESUP/Documentation+Issues+to+Serve+as+Motivation

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?

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

...

• Purpose
  • to document the OOTB experience
  • to document configuration options that change the OOTB experience (reference)
  • to demonstrate how to accomplish common tasks
• Audience
  • Faculty should be a primary audience
  • Instructional designers
  • Could we consider faculty as end-users and students as end-end-users?
    • Faculty design choices influence student user experience
  • Advanced users: document permissions, special fields, settings, properties, and what they mean.
• Content
  • Beginner and Advanced levels would allow a faculty member to get a quick start with the basics and then later explore the more complex features
  • Conceptual Introduction - brief description of the purpose of the tool
  • Task oriented instructions
  • Brief (3 min?) screencast
  • Annotated screenshots

...

• Sakai Knowledge Base, managed by Indiana: https://www.indiana.edu/~sakaikb/

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

...

• Provide an easily editable platform for central documentation
• Provide guidance on what should be contributed back, and how
• Provide ways to point to localized documentation to supplement the core help files
• Have a vetting process in place to accept/reject contributed changes
• Make the help files easily "subscribable", customizable, exportable in multiple formats for quick local updates
• Do we need a documentation policy?  To be discussed at EuroSakai 2011.

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)?

• What is the difference between localization and branding?
  • Good question
    • I offer the suggestion that "branding" refers to the name and/or logo that an institution may give their instance of Sakai.  Michigan calls their instance "CTOOLS," Indiana "Oncourse," VirginiaTech "Scholar," etc.
    • Localization would refer to providing the same helpful information in multiple languages or regions, e.g. Spanish, English (UK), English (US), French, German, Chinese, Japanese, etc.
• For "branding," can we provide definable fields.  One definable field might be "brand name" that would default to "Sakai" out of the box (OOTB) but allow an institution to replace with their local instance's name.  The text of the help files would either dynamically (or periodically) lookup and insert the local brand name into the help files.  Similarly, a definable image source could be provided for a brand logo and placed into the help files.  And definable formatting colors could also be available, which would insert the colors into the appropriate CSS and/or HTML source. (Adam: It would also be useful to have a look-up table of local tool names (unless these can be be pull in automatically from the tool definition file))
• Customization: Each institution goes into the help files and purges tools that are not used, or takes out references to a certain role, etc. It would be nice if those customizations could be easily visible to all, so that they could be integrated in your local help files.

11. "Wish list" thoughts?

• Low-Tech Quick Looks-- static web pages (even simpler than videos) that faculty can look at in a spare 5 or 10 minutes, with boxes and arrows, like Oxford's explanation of the Wiki tool.  Public, with no login required.
• Pop-up on initial entry to site
  • On first access to a site, person is presented a simple welcome pop-up with three options: video overview, getting started tutorials, or exit.
  • Pop-up is role-based. Students see student materials, instructors, etc.
• Tool help
  • Tool-based help pages should be easily navigated by the person's role in the site (yet other role materials accessible but not cluttering the current view).  Students report getting lost in the help pages since it's not clear which pages are for them.
• A document librarian
• Maybe we need to define a set of community guidelines (a manifesto?) on what constitute good user design. For instance, tools designed with the user in mind, with embedded help prompts or a clear workflow, don't require as much documentation. The closer the help is to the task, the better.

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

• Community: Help files for the Knowledge Base are reviewed by the Adademic Computing team, and updated if necessary by Jackie Mai, User Experience specialist.  Done for 2.7/2.8 in November.
• Local (CourseWork): Extensive documentation site, with Help files following, but not identical to, the KB files; and other how-to documents, FAQ, and outstanding issues, and release notes for new CourseWork deployments (every quarter or so).

For developers and deployers:

• Many of the current resources labeled "Documentation":
  1. Sakaiproject.org/documentation
  2. Confluence "Project: Documentation"

• Installation and configuration guides

• Glossaries
  1. http://confluence.sakaiproject.org/display/3AK/Glossary+of+Terms
  2. http://confluence.sakaiproject.org/display/KERNDOC/550+-+Glossary

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.