Anchor Top Top Table of Contents
Links for Reference
QA servers:Marist QA server:
Unless otherwise stated, all documentation should be done using the Sakai 20 test instance - https://qa01sakai.marist.edu/portal (Sakai is updated daily for new fixes, but content is not purged.)12.x maintenance branch (either MySQL or Oracle) on nightly servers: http://nightly2 (Nightly servers are wiped each day. Content is not retained)
Preview (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.
The Apereo Foundation maintains the subscription to ScreenStepsLive for our collaborative authoring group. We are currently limited to 10 author accounts.
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 firstname.lastname@example.org 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/
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.
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.
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.)
Please contact Wilma Hodges (email@example.com) or Neal Caidin (neal.caidin@apereo or firstname.lastname@example.org) if you have any questions about authoring Sakai help using Screensteps or the style and process guidelines above.