OLE User Documentation Training

The Plan for User Documentation

OLE intends to have two types of User Documentation (there will be more documentation, especially with later releases, but this page focuses only on User Documentation). One will be Overviews and the other will be what we are playfully calling "The Big Book" of OLE.

1. The Overviews will incorporate overviews and processes of each module to explain to users the big picture of how OLE functions.
2. The Big Book of OLE will include all the details of every e-doc within OLE. This will eventually progress into online help.

For example: a user will learn from the Overviews that they need to create a requisition to pre-order titles and that will become a purchase order, but will be directed to the Big Book to find the specifics of how to fill out a requisition, the definitions for data input, next steps, etc.

Writers Responsibilities

Writers for OLE Documentation are responsible for:

• Obtaining content from functional specs, SMEs, and their own work in OLE's UI.
  • Test Scripts have also proven useful, there may be comments still in the documents that still refer to OLETS cases.
• Writing clear and concise user documentation in the OLE templates provided, according to OLE team standards for content, usage, punctuation, etc.
  • Please take a few minutes to review the KFS User Documentation Standards.
• Working with SMEs while preparing the original draft and during review cycles in order to improve the quality of content and presentation.
• Storing all drafts as attachments to the Documentation Sandbox
• Letting Nora know when drafted pieces are ready for review.

Where to Start on the Big Book

These have already been started from the 0.6 Drivers Manual and KFS Documentation (where appropriate). You will find them in the Documentation Sandbox. These will need to be very detailed but a lot of the work has already been accomplished.

• Read through what is already there.
• Accept changes if you know something is correct.
• Check through comments left by Nora. Please ignore "link" comments - Nora needs to tend to when finalizing the document.
• Review functional specifications, data requirements, OLE and OLETS Jira tickets for information.
• Think through the workflows, is everything addressed?
• Roles/permissions - are they accounted for? S&A especially will need to be reviewed for this.
• Make notes of gaps, important things that will be addressed in 1.0 or beyond.

Upload drafts in the sandbox (you will need to be logged in). Let Nora know when a document is ready for review.

Diagrams, workflows in the Overviews and Big Book

There are diagrams included within the Big Book documentation. These have been done in Visio in the past but from now on they will be created using Gliffy. For consistency, these will eventually need to be recreated within Gliffy with guidelines (TBD).

Screenshots in the Big Book

Make a comment for any screenshots that need to be included or replaced later.
As needed:

• Create output in .png format.
• To improve legibility of text on the image, capture the largest image possible given the size of the computer screen you are using. Oversized screen images can be resized as needed within the Word doc.
• For each screen capture of an e-doc, only capture the e-doc.
• In images of full screens, do not include action buttons at the bottom of the screen because these change depending on a user's permissions.
• For your reference, this is the standard in which screenshots should be included in our documentation:
  • For e-docs accessible from the Main Menu tab:
    • Under 'Document Layout', insert a single full-length screen shot showing the entire e-doc as it displays when the user first accesses it from the menu. For most e-docs, this means the screen will be shown in create mode rather than edit mode. If the initial display is a search screen, use separate screen shots to show the initial search screen, the results of a search, and the screen display after selecting one of the e-docs listed in the results.
    • Under the subheading for each tab, insert a screen shot of the tab.
    • Under 'Process Overview', if you are documenting e-doc-specific processes and if screen shots will aid in user comprehension, include shots of parts of the screen that change.
  • For e-docs accessible from the Maintenance menu tab:
    • Include only a full-length screen shot of the e-doc in edit mode. Do not include separate images of individual tabs.
  • For e-docs accessible from the Administration menu tab:
    • Include only a full-length screen shot of the initial display of the e-doc.

Links

Please leave Nora's comments for links - she'll revisit them during finalization.

There are already some links within OLE's Documentation. However as this is still a work in progress, if you are unsure of the precise location just leave a comment. This way it can be revisited in the future.

For all linking, start on a fresh line and begin with:

Infrastructure Basics

OLE has inherited basic Kuali functionality - E-docs and Maintenance documents, navigation, routing and workflows. This information, adopted from KFS, has already been posted on the wiki (Infrastructure basics). To keep documentation from becoming bigger than it needs to be, we will link to the information within the child pages whenever possible.

OLE Test Environment

Please use the . This environment has a code promotion every other Friday. See the release documentation to view the schedule and development progress.

User IDs

In OLE, different users can perform different activities. Consequently, you need to log in as (that is, impersonate) the appropriate user whenever you need to access a particular e-doc or perform a specific task (such as editing or approving) the e-doc. Be sure that these users are tracked/noted in the documentation (Roles and sample users).

If you are not familiar with logging in and out or switching users within OLE, please review the appropriate section under Navigating through OLE.

Finding which IDs to use

Some IDs are already documented within the Big Book. Others will be noted in specifications and test scenarios.



Some information on this page has been modified from KFS Information for Writers