| Wiki Markup |
|---|
{note}
If you are uncertain about anything in the documentation or something on this page is unclear, please contact Nora: email or skype
{note}
{section}
{column:width=50%}
h3. Purpose
This space provides information and tools for the development of end user documentation for OLE. Most end users work in various departments within the library system and are not IT specialists. OLE documentation for end users is intended for use as aids in training new users and, thereafter, for reference.
*Links for more Information:*
* [User Documentation Plan|OLE:User Documentation Planning] for more information about each type of documentation OLE plans to provide.
* [Infrastructure basics|OLE:OLE and Rice-KFS] to see/learn more about global functionality. Read more [below|#infrastructure].
*Links to Tools and Documentation Templates:*
* [Documentation Sandbox|OLE:0.8 User Documentation Sandbox] for the works in progress of the 0.8 documentation.
* [Gliffy Instructions|OLE:OLE Gliffy Sandbox Instructions] for use on the wiki.
* [OLE Gliffy Sandbox|OLE:OLE Sandbox- Saved Gliffy's] for creating diagrams.
{column}
{column}
{panel:title=Contents|borderStyle=dashed|borderColor=#97A0A9|titleBGColor=#F2F8FF|bgColor=#F8FCFF}
{toc:outline=false}
{panel}
{column}
{section}
h3. The Plan for User Documentation
OLE intends to have two types of User Documentation (there will be [more documentation|OLE:User Documentation Planning], 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.
# The Overviews will incorporate overviews and processes of each module to explain to users the big picture of how OLE functions.
# 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.
h3. 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|https://wiki.kuali.org/display/KULKFS/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|OLE:0.8 User Documentation Sandbox]
* Letting Nora know when drafted pieces are ready for review.
{HTMLcomment}
h3. Where to Start on the Overviews - {color:red} drafts are done{color} - skip this section. YEAH :)
SME teams reviewed the modular overview documents in October. These are broad overviews that were created for developers and will need to be modified for librarians. You will find them in the [Documentation Sandbox|OLE:0.8 User Documentation Sandbox].
As you read through the overviews -
* Is there anything missing?
* How would you rewrite the introduction for library staff? Will OLE newcomers understand?
* Is the content directed at the library staff? How can it be rewritten to do so? What would your peers need to know?
* How would a librarian or staff member complete the tasks and processes? Have the general steps been captured?
** Don't get too caught up in details here but make comments as placeholders to link to the Big Book.
* Are there use cases or examples that would help explain the workflows?
* Review the functional specifications of the SME team; are there things that should be added from the specs to the Overviews?
(i) Upload drafts in the sandbox (you will need to be logged in). Let Nora know when a document is ready for review.
{HTMLcomment}
h3. 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|OLE:0.8 User 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.
(i) Upload drafts in the sandbox (you will need to be logged in). Let Nora know when a document is ready for review.
h3. 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 {color:red}(TBD){color}.
h3. 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.
h3. 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.
(i) For all linking, start on a fresh line and begin with: !link.png!
h5. Infrastructure Basics {anchor:infrastructure}
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|OLE:OLE and Rice-KFS]). To keep documentation from becoming bigger than it needs to be, we will link to the information within the child pages whenever possible.
h3. OLE Test Environment
Please use the {link-window:http://tst.ole.kuali.org/|scrollbars=true|menubar=true|location=true|statusbar=true|resizable=true|width=800|height=600|icon=false}OLE Test Environment{link-window}. This environment has a code promotion every other Friday. See the [release documentation|OLE:OLE Release Documentation - for Milestone 0.8] to view the schedule and development progress.
h5. 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 [OLE:Navigating through OLE].
h5. 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|https://wiki.kuali.org/display/KULKFS/Information+for+Writers]| Note |
|---|
If you are uncertain about anything in the documentation or something on this page is unclear, please contact Nora: email or skype |
| Section |
|---|
| Column |
|---|
| PurposeThis space provides information and tools for the development of end user documentation for OLE. Most end users work in various departments within the library system and are not IT specialists. OLE documentation for end users is intended for use as aids in training new users and, thereafter, for reference. Links for more Information: Links to Tools and Documentation Templates: |
| Column |
|---|
| Panel |
|---|
| borderColor | #97A0A9 |
|---|
| bgColor | #F8FCFF |
|---|
| titleBGColor | #F2F8FF |
|---|
| title | Contents |
|---|
| borderStyle | dashed |
|---|
| |
|
|
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.
- The Overviews will incorporate overviews and processes of each module to explain to users the big picture of how OLE functions.
- 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.
- 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.
| HTML Comment |
|---|
Where to Start on the Overviews - drafts are done - skip this section. YEAH  SME teams reviewed the modular overview documents in October. These are broad overviews that were created for developers and will need to be modified for librarians. You will find them in the Documentation Sandbox.
As you read through the overviews - - Is there anything missing?
- How would you rewrite the introduction for library staff? Will OLE newcomers understand?
- Is the content directed at the library staff? How can it be rewritten to do so? What would your peers need to know?
- How would a librarian or staff member complete the tasks and processes? Have the general steps been captured?
- Don't get too caught up in details here but make comments as placeholders to link to the Big Book.
- Are there use cases or examples that would help explain the workflows?
- Review the functional specifications of the SME team; are there things that should be added from the specs to the Overviews?
 Upload drafts in the sandbox (you will need to be logged in). Let Nora know when a document is 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: 
Image Added
Infrastructure Basics
| Anchor |
|---|
| infrastructure |
|---|
| infrastructure |
|---|
|
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