Page Comparison

...

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

...

...

• 1. http://confluence.sakaiproject.org/display/KERNDOC/550+-+Glossary

For Portfolio, 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.