Documentation Templates and Guides for SMEs

User Documentation Plan

With the 1.0 release, we implemented online help using DocBook.  DocBook is an open standard of XML markup that allows you to structure documentation into books or articles.  We are now using Oxygen to edit the DocBook books.  We are not expecting functional SMEs to modify the XML within Oxygen but will create the content using Word templates provided below.  As some documentation only needs modifications, separate documents have been created with some content included.

Steps for OLE User Guides

1. Download a copy of the template, follow the directions in red to help fill out the content; work with other SMEs to complete
   1. KFS User Documentation Standards has helpful information about writing technical documentation.
2. Upload your document to Documentation 2.1 or Documentation 3.0 Google Drive Folder
3. Peer review
4. Let Nora know when you're done

If there is only additional information needed, find the link to the document in the jira.

1. Edit the document/work with other SMEs to complete - PLEASE MAKE CHANGES IN A DIFFERENT COLOR TEXT; use strike through text to indicate deletion.
   1. KFS User Documentation Standards has helpful information about writing technical documentation.
2. Peer review

Templates

TemplateEDoc.docx - for standard OLE e-docs. E-docs are for record keeping (financial documents, editor, etc).

TemplateInterface.docx - for OLE Interfaces.  Interfaces are where action occurs (circulation, transferring records, etc)

TemplateMaintenanceDoc.docx - for OLE Maintenance e-docs.  Maintenance e-docs manage the reference tables for e-docs (often found under an admin subheading)

TemplateBatchProcesses.docx - Describes batch processes which are generally run outside of regular operating hours.  Used in user documentation to give descriptions as needed.

Additional tips and helpful information

Screenshots

As needed:

1. Create output in .png format.
2. Add images as separate files to the designated document file within the Documentation 1.6 or Documentation 2.0 Google Drive Folder.
3. 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 in Oxygen.
4. If you are calling out items on your screenshot, please use classic/standard blue.
5. For each screen capture of an e-doc, only capture the e-doc.
6. For your reference, this is the standard in which screenshots should be included in our documentation:
   • For e-docs:
     • 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 maintenance e-docs:
     • Include only a full-length screenshot of the e-doc in edit mode. Do not include separate images of individual tabs.
   • For admin e-docs:
     • Include only a full-length screenshot of the initial display of the e-doc.
   • For interfaces:
     • Include an initial view screen shot.
     • Include screenshots to note steps in the process as necessary.

Infrastructure Basics  

OLE has inherited basic Kuali functionality - E-docs and Maintenance documents, navigation, routing and workflows. This information, adopted from KFS, is available from the Documentation Portal (OLE Basic Functionality and Key Concepts) To keep documentation from becoming bigger than it needs to be, we will link to the information within the child pages whenever possible.

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. If functionality is blocked without a particular ID being used, please be sure that these users are tracked/noted in the documentation (Roles and sample users). If you are not sure which ID to use, check test scenarios or specifications.

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