Sakai Documentation Project Style and Process Guidelines
Links for Reference
Unless otherwise stated, all documentation should be done using the Sakai 20 test instance - https://qa20-mysql.nightly.sakaiproject.org/ (server refreshed weekly)
You may preview and comment on published Sakai Documentation at: https://sakai.screenstepslive.com
Note that unpublished or in-progress documentation, such as the Sakai 20 manuals, require editor permissions in Screensteps for access.
ScreenStepsLive
The Apereo Foundation maintains the subscription to ScreenStepsLive for our collaborative authoring group. We are currently limited to 10 author accounts.
Contributing authors will have editor accounts created for them by Apereo. Contact Wilma Hodges (wilma.hodges@apereo.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 previewing the documentation on https://sakai.screenstepslive.com and adding comments using a “read-only” account that does not count against the licensing numbers.
If you have your own Screensteps account for your institution and would like to contribute content, please contact wilma@longsight.com for more information on copying or contributing to Sakai community documentation.
Refer to the ScreenSteps website for downloading and purchasing information: http://www.screensteps.com/
Document Organization
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:
User (includes both Instructor and Student oriented articles)
Admin
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.
Contrib Tools (e.g. Gradebook2) are not included in the Core documentation release. If available, help for Contrib tools may be exported separately and added to the help for a given instance. Not all Contrib tools have help available in Screensteps format.
For documenting the Mobile view, if it makes sense, and does not make the article too long/unwieldy, you may add a section and/or additional screenshots illustrating the mobile view of the steps. The primary focus is in documenting the desktop view, but we can add instructions for mobile users as needed.
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 core tools have been created in ScreenSteps. Additional manuals/chapters will be added as needed.
Editors may assign themselves articles for review and updating. Please only claim articles that currently have no owner.
If you would like to modify or edit an article owned by someone else, please use the “Note” option in Screensteps to request the owner's permission and/or notify the owner of any changes, comments, questions or suggestions.
Feel free to add new articles within appropriate chapters, with or without content. Blank articles may be added as placeholders for content that you intend to create.
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, leave the status set to "Needs Update" until you are finished editing.
When you have finished editing or updating an article, please mark it as “Needs Review.”
When saving your edits, please use the "Save as Draft" option. Do not publish the article until after it has been marked "Approved." (Typically you will not need to do this yourself, it will be published for you upon approval.)
Screensteps 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.
The help articles are organized in manuals specific to each version and language. Please DO NOT move articles to other manuals. When we make a new manual for updating the content to a new version or language, copies of existing content or language are made for the purpose of updating. Please work only within the new manual when doing updates. If needed, existing articles may be copied or duplicated into a new manual for updating. However, they should not be moved, as this will disrupt the content in the existing manual.
Text Guidelines
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.
If there are steps which make mention of clicking on various icons, please include the alt text description where possible. For example, in the article titled, "How do I read, post, or delete Chat Room messages?" the step "Delete a Chat Room message" talks about seeing a trash can icon. Screen reader users will never see the trash can icon, because the alt text for the trash can icon says, "Delete this message." Therefore, the documentation should read "click the trash can icon (Delete this message)" (with "Delete this message" in bold because you click on it).
Image Guidelines
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 or content area.
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. If the alt text simply repeats the step text, then you should delete the alt text to avoid unnecessary repetition for screen readers.
Metadata
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 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 the ___ tool?” overview article for each tool, an article tag should also be added with the tool id. Tags are only added for the tool overview article. They must be added in the web interface. (See example tag.)
The “search” metadata field should include any alternate search terms that you anticipate users might search for in relation to the article.
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)
Contrib Tools
As noted above, Contrib Tools are not included in the Core documentation release. If available, help for Contrib tools may be exported separately and added to the help for a given instance. Not all Contrib tools have help available in Screensteps format.
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. Contrib tool documentation will be available for download from Github.
Workflow Guidelines
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 Doc Project guidelines, current text of relevant Help files, and articles in progress, if necessary, for context.
Work through the Sakai functionality for the current version on the test servers.
For the procedural aspects of the article, verify that the steps are still correct for this version of Sakai. If the steps are incorrect or missing, update the article content to reflect the changes.
In most cases, each step will have one image illustrating the step action.
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 walking through the steps 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.)
Questions?
Please contact Wilma Hodges (wilma@longsight.com or wilma.hodges@apereo.org) if you have any questions about authoring Sakai help using Screensteps or the style and process guidelines above.