This page is intended for the use of people who create tutorials on the iPlant Wiki for iPlant users. This page describes the process for how to add or move a tutorial to the iPlant Wiki Tutorials space (here).

Definitions

Documentation, tutorials, and user manuals are frequently mentioned as one and the same. They are not.

• A tutorial is a video or Wiki document that instructs users on how to use a particular or specific aspect of a CyVerse application or service. Tutorials run the gamut from scientific tutorials and workflows for how to use a complex app or process (some of which may be in this space while others are in the Learning Center), to YouTube videos, video tutorials, and more. All tutorials have been moved to this space so they can be found and accessed by our users.

• Documentation in the CyVerse world encompasses user Help housed on the Wiki:
  • Discovery Environment (using the DE framework)
  • Atmosphere
  • Getting started with CyVerse
  • Data Store
  • User Management portal
  • BisQue

• User manuals are the pages edited by the app's integrator for how to use that app, and they often include sample data files for test-driving the app. They are viewed in the app information in the Apps window and the pages themselves live on the Wiki.

Adding a tutorial to the list

This space is the repository for all tutorials and learning materials. You can work on an unfinished tutorial in your personal space, then move it here. Move it into the correct folder. You may need permission; if you don't see Edit at the top right of the page, email me and I'll get it straightened out.

Updating the Tutorials List

1. Log in to the Wiki.
2. Open the Learning Materials Table of Contents page.
3. Click Edit. (If Edit isn't available, ask the Space integrator for permissions.)
4. If you need to add a new row, in Rich Text view, click the last row in the table and then click to add a new row.
5. Click in the left cell and enter the title of your tutorial.
   
   • Don't start it with "Tutorial" on something like that since users will be sorting on the title.
   • The title helps users know what your tutorial is about. It should be short, clear, and concise. There is a lot of content on the Wiki. Creating a good title is the first step in making sure your tutorial can be found and viewed by users.
6. Copy the URL from the your tutorial.
7. Add the link to the title in the table.
   
   1. Highlight the title and click .
   2. Click Web Link on the left, paste the URL to your tutorial, and then click Insert.
8. Enter your last name and fill in the other columns.
9. Click Save.

Moving a tutorial

You can move a tutorial to this space; please read through the notes above about titles for the tutorial. You may need permission; if you don't see Edit at the top right of the page, email me and I'll get it straightened out.

1. To move a tutorial to this space, go to the tutorial file on the Wiki.
2. Click Tools and then click Move.
3. Search for the Tutorials space.
4. Click Move.

Creating a tutorial from scratch

If you just want to start creating your tutorial in this Wiki space, that's great.

1. Log in to the CyVerse Wiki.

2. Open the Tutorials Table of Contents page.
   You can add the space to your Favourites space list by clicking the star to the right of the space name:

   

Step 1: Add the page and enter the title

The title helps users know what your tutorial is about. It should be short, clear, and concise. There is a lot of content on the Wiki. Creating a good title is the first step in making sure your tutorial can be found and is viewed by users.

1. Click Add at the top right and then click Page. (If Add isn't available, you may need to ask the Space owner for permission to add a page.)
   
2. In the New Page field at the top, enter the title of the tutorial, using this format: App name: Tutorial title
   Example

   BisQue: Overview

3. Click Save.

Step 2: Lock 'er down

It may take you awhile to complete your tutorial so it's a good idea to lock it down until it's ready for the world. That's done with restrictions to the page. Once it's ready for prime time, you'll remove the restriction.

1. Point to Tools at the top right (not in Edit mode) and then click Restrictions. (If it's not available, ask the Space owner for Restriction permissions.)
2. Verify Restrict viewing of this page is selected.
3. Click me (or your team members, your choice) and click Save.

Step 3: Add the content

1. Click in the text block and start typing, or paste in your text.
2. View your text in Rich Text or Wiki Markup. Rich Text gives you a WYSIWYG view of the text and graphics as you're typing it, while Wiki Markup lets you edit the tags with a bit more granularity. The Help Tips panel on the right helps with the Wiki markup.

Insert graphics

First you upload the graphic to the page, then you insert the image on your page.

1. Click where you want the graphic.
   • If using Rich Text, click Insert, and then click Image.
   • If using Wiki Markup, click .
2. Browse to your image and click Insert.
3. Click Preview to make sure it's where you want it to be. Edit it as needed (easier in Wiki Markup).

Step 4: Save and preview the tutorial

Click Save. Often.

To see how your tutorial will look, click Preview.

Step 5: Remove the page restriction

1. Point to Tools (not in Edit mode) and then click Restrictions.
2. Click Remove restriction.
3. Click Save.

Step 6: Add a link in the Tutorials Table of Contents table to your new page

1. Open the Tutorials Table of Contents page.
2. Click Edit.
3. In Rich Text view, click the last row in the table (or wherever you want to add your link) and then click to add a new row.
4. Click in the left cell and enter the title of your tutorial.
   The title helps users know what your tutorial is about. It should be short, clear, and concise. There is a lot of content on the Wiki. Creating a good title is the first step in making sure your tutorial can be found and viewed by users.
5. Add the link:
   1. Highlight the title and click .
   2. Click Recently Viewed on the left.
   3. Click the name of your tutorial and then click Insert.
6. Click in the right cell and enter a short description about your tutorial.
7. Click Save.

After your tutorial is available to the public

Add some labels for better findability (optional)

Labels are metadata about the page. They help users find your tutorial if they're looking for your topic area. Wiki labels are not as sophisticated as Google metadata but they can help users find your content if they're searching all the Wiki spaces.

1. Click in the Labels or Add Labels field at the bottom of the page.
2. Enter the meat of what your tutorial is about.
   • Leave out extraneous words like the, and, of, etc.
   • Use words you know people will want to search on; for example, genome or RNAseq.
   • For phrases, enter a hyphen between each word to keep the words together in search results.
   • Enter different variations of the main words. For example, you might enter add-dataset, adding-datasets, etc. Wiki markup isn't smart enough to understand stemming (like add, added, adding), so the variants help with findability.
3. Click Done.
4. Save your page if you're still in Edit mode.
5. Test your page by entering some search queries in the top right search field, which searches the whole Wiki.

Watch your page

For any tutorials you created on the Wiki, you'll be emailed automatically if someone adds a comment to your page.

You may want to consider making it a Favorite by pointing to Tools (not in Edit mode) and then click Favourite.