Overview

Robin suggested that we lock down the purpose of the help files in general before we launch into review, revision, and recommendations.

Robin Hill writes:

The Sakai Knowledge Base is a set of files displayed via the CLE Help button that provide immediate procedural guidance, tool-based, to end-users in "maintain" and "access" roles, with respect to the Sakai instance running. Information contained therein covers the normal cases and workflows aimed at standard daily tasks. The files are managed by Indiana but written and maintained by the institution contributing the tool.

Alan Regan's feedback:

• Great job!  Some of the things I really like about the above statement:
  • Defines end-users as the primary audience.
  • Defines scope (for tool details only, for immediate help, for CLE not OAE, etc.).
  • Identifies the current group that manages the files, the Indiana KB group.
  • Identifies the typical writers of the pages, the team or institution contributing the tool.
• Ares to consider:
  • What about: The purpose of the built-in Sakai Knowledge Base is to help end-users, like instructors and students, effectively use the features of the system. Organized by tool, the help pages are created with accurate and useful information written in human-friendly terms with the end-user in mind.  (I'd like to toss in "so that they can accomplish their daily tasks quickly and easily" but the sentence is probably too long already?)
  • For the current documentation project, we can then limit scope to CLE, etc...?
  • I thought that the "instructors" and "students" might resonate more than than "maintain" and "access."  The tool was developed for educators by educators, so I am coming from the perspective of education as a better fit.  Of course, many types of organization can and do use the Sakai platform... but I admit, I am biased toward education!  :)
  • Should we state that files follow consistent standards?
  • Based on this statement, where do other elements like "best practices" or "use cases" go?
  • Should we note that the content is generally written by the team or institution contributing the tool, in collaboration with (or edited by) KB managers and the community of users?

Mathieu's feedback:

• As convoluted as it might sound, I agree that the terms "maintain" and "instructor", and "access" and "student" must be included in the definition. I don't you can get away with using one or the other, especially if the goal is to make the knowledge base something that can be used out of the box.
• I like the fact that we limit the scope to the CLE. We might discover new ways of documenting that will make more sense for the OAE when the time comes.
• I would change the last sentence to: The files are managed by Indiana University, but are written and maintained primarily by the institution contributing the tool, with edits and additions provided by members of the Sakai community.
• In my opinion, use cases should be managed locally, and inserted as callouts or references in the help files as needed. Those would point to external sources like youtube videos, opened practices, local articles explaining a particular practice, etc. I see these as I would see cases included in an open textbook. The theory is the textbook, examples are customized to the audience.