Links for Reference
Sakai 10 draft release notes, including new features (in progress) https://confluence.sakaiproject.org/pages/viewpage.action?pageId=86245732
Preview and comment on Sakai Documentation: https://sakai.screenstepslive.com
The Apereo Foundation maintains the subscription to ScreenStepsLive for our collaborative authoring group. We are currently limited to 10 author accounts for the pilot phase of this project.
Contributing authors will have editor accounts created for them by Apereo. Contact Neal Caidin (firstname.lastname@example.org) for more information or to request access.
Community members who would like to contribute but do not have author accounts may participate in the following ways:
Review existing documentation and provide comments, feedback, and suggestions to the authoring team by logging in and adding comments using a “read-only” account that does not count against the licensing numbers.
Download and install a copy of Screensteps 3.0 stand-alone desktop authoring software to author content locally and export articles in ScreenSteps packaging format. Exported content packages should be emailed to email@example.com for import into the Apereo documentation site.
ScreenSteps 2.9 free 14-day trial version download http://www.bluemangolearning.com/screensteps/downloads/
ScreenSteps 2.9 pricing information (academic discount available) http://www.bluemangolearning.com/screensteps/purchase/
ScreenSteps 3.0 pricing information (academic discount available)
Manuals in Screensteps are organized by version of Sakai and by user role
Sakai online help landing page “About Help” advises users that they may search help all available help, but that they must have appropriate roles/permissions to perform some tasks.
Current manuals included in the online help are:
Admin (in development, will be added for 10.1)
Contrib (planned for development, will be added for 10.1 or later)
Chapters within manuals are organized by tool
A “What is x tool?” article that serves as an overview is the first item in each chapter. This page will serve as the landing page for that tool in the context-sensitive help within Sakai.
Articles within each chapter are organized by task.
General Process Guidelines
We will follow a "document as you go" approach where we write up the most commonly asked/needed articles first, and then add to the article set as additional user needs or questions surface. We don’t need to document everything exhaustively right away (particularly when it comes to advanced features or edge scenarios), but focus more on the tasks users need to perform most often.
Manuals for user roles and chapters for Sakai 10 core tools have been created in ScreenSteps. Additional manuals/chapters will be added as needed.
Editors will be assigned articles to update or review. You are also free to assign yourself an article that currently has no owner. However, please do not modify the owner of an article without the owner’s permission.
If you modify or review an article owned by someone else, please use the “Note” option in Screensteps to notify the owner of any changes, comments, questions or suggestions.
Feel free to add new articles within appropriate chapters, with or without content.
If an article is empty (i.e. article is a placeholder for a task yet to be documented), be sure to mark it as “Needs Content.”
If an existing article needs to be updated to incorporate new features or other changes, mark it as “Needs Update.”
If you are actively working on an article, mark it as “Draft” until you are finished editing. Check it in as “Published” when you are finished editing so that it is visible to reader accounts for posting comments.
Please be sure to check articles back in when you are not working on them, even if the article is not yet finished (i.e. still a draft). Users cannot modify articles that are checked out by another user.
When you have finished writing an article, please mark it as “Needs Review.”
Admin users will review articles for consistency and mark them as “Approved” when review is complete and article is ready for inclusion in help. Please note that modifications may be made by the reviewer, if needed, prior to approval.
When in doubt, use Chicago Manual of Style format.
All help articles should be geared toward a primary audience (e.g., instructors, admins, students) and included in the appropriate manual. (Lessons which are applicable to more than one role may be copied to other manuals, or referenced/linked in multiple manuals if needed.)
Site Maintainer/Owner = Instructor and Participant = Student. (These terms may be used interchangeably and we can mention this equivalency.)
TA specific content will be documented in a sub-section of the instructor manual.
Custom roles can be covered elsewhere, perhaps in a separate manual or chapter dealing primarily with permissions.
Article titles should be in the form of simple questions (e.g., “How do I post a Forum message?”)
Each tool should have an “overview” article titled:”What is the _____tool?”
IMPORTANT: Please keep step titles as short as possible. Additional explanatory text or directions may be added in the “Add paragraph text” area below the image in each step. However, long step titles can create issues with file and path max character length when exporting to HTML.
Keep each article as short as possible and focused on a single task.
Use language that is concise, to-the-point, and appropriate for the audience. (For example, with Instructors use more descriptive language; with Admins more technical language.)
Avoid passive voice whenever possible.
Whenever possible, steps should begin with active verbs like Select, Click, Edit, etc.
Capitalize feature or tool names.
For actions performed on items/buttons/links, the object of the action should be in bold (e.g., “Click the New Forum button.”)
Use “click” and not “click on” when describing an action (e.g., “Click the Save button.”)
Do not bold the period following bold text.
Use italics for Tip and Note text. Tips/Notes should begin their own paragraph and be followed by a colon. Examples below.
A Tip provides a suggestion or best practice.
Tip: For events with no physical location, you could enter Online, or Via Meetings Tool, if you do not want to leave the event location blank.
A Note calls attention to an important feature or item information.
Note: The default location and availability of items in My Workspace may be customized by your institution.
Avoid the use of the term Sakai as much as possible to make branding easier for institutions who have customized the name.
All steps should be written such that they can be understood and followed with or without the accompanying image.
Close quotation marks before any punctuation mark that’s not part of the text on the screen, or whatever it is you’re representing with the quotes.
When referencing another tool or action that has an article associated with it, hyperlink the tool or action to the chapter or article associated with it the first time it appears. For example: In the Syllabus tool article, I mention the Rich Text Editor. I will hyperlink that text (the first time it is mentioned) to the Chapter on Rich Text Editor.
Use one of the QA servers with the default Sakai skin for all screenshots.
In most cases, an image will be included with each step.
Follow the default practice of image above paragraph text within each step.
Limit the image selection to the documented tool.
Avoid full screen/browser window captures unless absolutely necessary.
Whenever possible, focus on the item or tool in question to crop out as much of the surrounding branding as possible.
Do not truncate text or cut off surrounding images if possible. Look for natural breaks in the layout so that images don’t look choppy.
The landing page for each tool will include an image of the Tool Menu with both the tool above and below in the screenshot, no hover color, and a red box highlighting the tool in question.
The Tool Menu image is included for the first article in each chapter only (i.e. the “What is…” tool landing page article). See example.
Subsequent articles within a chapter will not include an image of selecting the tool with the first step, although the step title “Go to X the tool.” and paragraph text “Select the X tool from the Tool Menu of your site.” should be included. See example.
Use the default annotation settings in ScreenSteps for color and line weight of boxes, arrows, highlighting, etc.
Avoid adding too many annotations to a single image. In general, you want to direct the eye to one or two items per image.
On images where multiple areas are discussed in one step, use sequenced numbers. (Paragraph text within the step should also be numbered to reflect numbered items in the image.)
Use the red outline box to indicate buttons, links, or other items where the reader will perform an action.
Use the yellow highlight to call attention to additional features or information.
Use arrows sparingly, and only when needed for clarification.
When appropriate, alternative text (i.e. alt tags) should describe the informational purpose of the image. Screensteps will add alt tags automatically with the title of the step, but the alt tag may be modified if needed.
You can enter the article metadata in Screensteps using the “Article Inspector” in the desktop editing client. (See example metadata entry screen.)
Be sure to add a version tag, title, description and keywords to each item as you create it.
The “title” metadata should be the same as the article title.
The “description” metadata field should be the Sakai tool id. For example, the description for one of the articles in the Forums chapter, such as “How do I delete a Forum?” should be: sakai.forums
Note: On the “What is…” article for each tool, the description should be the Sakai tool id, a comma, and “main” to indicate that it is the tool landing page. For example, the description for the “What is the Forums tool?” page should be: sakai.forums, main
The “search” metadata field should include any alternate search terms that you anticipate users might search for in relation to the article.
Tag the article with the Sakai version number. (If you are updating an existing article from an earlier version of Sakai, be sure to remove the tag for the earlier version.) For Sakai 10, the tag should be the number “10” only.
List of terms
Note: We may add to this list as we go. Please use the following terms when referring to items/features in help.
Tool Menu (for the left navigation menu)
Rich text editor (for the CKeditor)
Reset button (for the two blue arrows that allow you to re-enter a specific tool at the top page of that tool)
Site Navigation (for the site tabs across the top)
An additional “Contrib Tools” manual will be added to the help documentation which contains Contrib tool help articles organized by tool.
Anyone may contribute; primary maintainers and/or users of Contrib tools are encouraged to update or contribute docs for inclusion.
If appropriate, links out to institution specific content may also be added for additional reference.
Since the Contrib tools are typically not enabled on the QA servers, any server may be used for screenshots. However, if possible, try to use the default OOTB Sakai skin for screen captures.
All contributed content will be reviewed for consistency and accuracy prior to approval for inclusion in help.
For authors with Apereo Screensteps access, please follow the workflow below.
Choose an article that is either (A) already assigned to you as the owner, or (B) unassigned with "Nobody" listed as the owner.
Change the owner of the article to your name (if not already listed).
Review these Sakai 10 Doc Project guidelines, current text of relevant Help files, and articles in progress, if necessary, for context.
Work through the Sakai 10 functionality on the test servers.
For the procedural aspects of the article, compose a series of steps with clear annotations.
For descriptions of multiple features in one screen image, provide numbered annotations of the user interface, with corresponding notes within that step.
Test your instructions by applying them on the test servers.
Add metadata to the article.
Check article in as "Draft, Needs Content" or "Draft, Needs Update" if you want to continue working on it; check article in as "Published, Needs Review", if you are done with the current revision. (Be sure to check in articles if you are not actively working on them, as no one else can make changes to an article while it is checked out.)
Please contact Wilma Hodges (firstname.lastname@example.org) or Neal Caidin (email@example.com) if you have any questions about authoring Sakai help using Screensteps or the style and process guidelines above.