Writing Quick Guide Tutorials in PSP 8
Tips for Tutorial Writers

Created June 21, 2003 © Copyright SuzShook
Property of SuzShook

	~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~
:	Translate this page into	:
:	Spanish | French | German | Italian | Portuguese | Norwegian	:
:	Free Translation	:
	~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~   :   ~

This tutorial is my own creation;
however, most of the techniques used in this tutorial, I have learned from others.
Therefore, if you recognize any contribution you have made, I thank you.
And I thank you as well for respecting this as my work by not posting it,
in whole or in part,
in any other location without written permission from me.

Individuals and PSP graphics groups are invited to share my tutorials with others with TEXT LINKS ONLY.
You can e-mail me to let me know you are adding one or more of my tutorials to your list if you like -
it's always fun to know who is doing them.

This is a followup tutorial to the Adding Tutorials As Quick Guides in PSP 8. This tutorial is written for tutorial writers who want to create their own Quick Guide tutorials in PSP 8. It contains hints and tips I've discovered in creating over 20 Quick Guides in the past several weeks. This tutorial contains guidelines for tutorial writers, and is therefore text-intensive.

Supplies - For this tutorial, you will need the following:

• Jasc's Paint Shop Pro 8 - you can get the 30-day trial version HERE.

~     ~     ~     ~     ~     ~     ~     ~     ~     ~

OK, now we're ready to begin.

~     ~     ~     ~     ~     ~     ~     ~     ~     ~

Part I - Introduction to Quick Guides

1. According to Jasc, "Quick Guides are short, fast tutorials that guide you through new tasks and projects using your own image." PSP has a facility for setting up these Quick Guides in the new Learning Center palette. Quick Guides can then be viewed within the PSP workspace as you complete the task they describe. Having the tutorial right in front of you while you complete a task makes the learning much easier.

2. Though these short, fast, reference-type tutorials are ideal candidates for the Learning Center, if you create your regular full-length tutorials following these guidelines, they will also work well installed in the Learning Center. This will make completing projects a lot more pleasant, to say nothing of the trees it will save!

3. One major difference between Quick Guides and full-length tutorials is in their disposition. Quick Guides would probably be retained within the Learning Center for future reference. Full-length tutorials, on the other hand, would probably be deleted or moved to a CD or another folder when the task they describe is finished, so they would not be installed into the Learning Center each time PSP is fired up.

4. Tutorial writers need to be aware that preparing a tutorial for the Learning Center - whether a true Quick Guide or a full-length tutorial - means you will be allowing the user to transfer all the images, scripts, and HTML you have created and written for the guide/tutorial to the user's computer. There are copyright issues involved here that some tutorial writers may be uncomfortable with. Definitely "no right click" writers, and those using encryption for their tutorials, will not want to use this method.

5. This tutorial is specifically geared towards Quick Guide formulation - however, the same guidelines can be used for preparing full-length tutorials for the Learning Center.

Part II - How To Set Up Quick Guides

1. To set up a Quick Guide tutorial, it must be installed within a Tutorial folder, created within a Category folder, which is located within the Quick Guides folder of My PSP8 Files. The complete path, then, to the tutorial location, would look like this:
   C:\My Documents\My PSP8 Files\Quick Guides\Category\Tutorial

   The Category folder can be called anything the user wants to name it, but you'll probably want to suggest a category name for the Quick Guides you create. The Category name is the one that shows up within the Learning Center palette in PSP.

2. You will need to provide specific instructions for the user on how to install your Quick Guides. If they are not installed correctly, they will not show up in the Learning Center.

3. Let's take a look at the Jasc Quick Guides folder. In this image, I colored the Category folders red (you can see 5 category folders), and the Tutorial folders blue (3 of those are visible in the Photo Projects category). I also highlighted in green the contents of one of the Tutorial folders called "Convert a photo into a greeting card":
   

4. There are several things to notice here. First of all, notice the HTML file for the tutorial - it MUST be called index.htm. Then, the Jasc-distributed Quick Guide tutorials always include 3 folders:

   1. A css folder, which contains the Jasc cascading style sheet document.

   2. An Images folder, which contains all the images used by the Quick Guide.

   3. A Scripts folder, which contains all the embedded scripts.

   This is one way to set up the tutorial folder for a Quick Guide.

5. Now take a look at my Quick Guides folder. Again, the Category folders are colored red (there are 3 category folders visible), and the Tutorial folders, blue (you can see 3 of those in the How-To Tutorials category). I've highlighted in green the contents of one of the Tutorial folders called "Autosave":
   

6. Notice again the HTML file is named index.htm, and I have no subfolders. I opted to do without the 3 folders Jasc uses, and include all scripts, images and the index file together within the tutorial folder. I find users sometimes have a difficult time unzipping files that contain folders, and the tutorial won't work if the user does not get the folder structure correct. Therefore, I eliminated the subfolders and placed everything together. It's a personal preference - either way works. Style sheets are optional, too - they can be used if desired, but are not necessary!

7. Either way you set up your Quick Guide tutorials, just remember these 2 things:

   1. The tutorial (along with all its images and scripts) MUST be placed in a Tutorial folder, within a Category folder, within the Quick Guides folder.

   2. The HTML file containing your tutorial MUST be called index.htm. No other name will work.

Part III - Quick Guide Formatting Hints and Tips

1. Never indicate the page width. If you are using tables, same thing - do not specify an exact width. In both cases, either let it default, or use percentages, so you do not force the user to scroll.

2. Keep images under 250 pixels at the widest, so the user will not have to scroll to view them. The page width - and thus the width of the text - will be AT LEAST the width of the widest image, so if you use large images, you force the user to scroll for both images and text.

3. When a larger image is required, use a small image or thumbnail within the Quick Guide which is clickable and links to a larger version of the image. Though there are many ways to set this up, I usually link to a new HTML page containing the larger image. When the user clicks on the small image, the larger image will replace the Quick Guide in the Learning Center, and can be viewed by scrolling as needed. The user need only click the "Go back a page" button at the top of the screen to return to the Quick Guide.

   To see this in action, load my Using PSP 8 Files in PSP 7 Quick Guide, which you can find at my website on the PSP 8 Quick Guides page.

4. When using a tool, include the tool image - this will help the user find that tool on the Tools toolbar.

5. Develop a style that you use consistently for Quick Guide tutorials. The Style used by Jasc is simple, easy to follow, and readily available by browsing any of their Quick Guides. I'd suggest looking at the Turning A Photo Into A Greeting Card tutorial, in the Photo Projects category folder. This Quick Guide has both "Choose this tool for me" and "Perform this step for me" scripts, as well as both a Notes and Tips section and a Learn More section.

6. I created by own template from one of the Jasc Quick Guides - I used their basic structure and added my own personal touches so that I have something I can consistently work with. You'll probably want to do the same.

7. The Jasc model has one piece of Javascript code at the beginning between these two comments:

   <!-- For Script Embedding, do NOT edit from here... -->

   <!-- ... to here. -->

   As directed, leave that code intact exactly as is. That code is required for embedding scripts.

8. At the spot you want to add a script link to your Quick Guide, add the following code (slightly altered from Jasc model - I do not use subfolders!). The parts you change are indicated in red:

   <img src="youricon.gif" width="??" height="??" align=middle alt="whateveritis icon">

   <a href="#" onClick="MM_goToURL('parent','YourScriptName.PspScript');return document.MM_returnValue">

   Perform this step for me</a>.

9. Use icons from the toolbars and menus to set off each "perform this step for me" line. The code above includes the icon separate from the link. If you want the icon to be part of the link, include it right before the words "Perform this step for me.", like this:

   <a href="#" onClick="MM_goToURL('parent','YourScriptName.PspScript');return document.MM_returnValue">

   <img src="youricon.gif" width="??" height="??" align=middle border=none alt="whateveritis icon"> Perform this step for me</a>.

10. Keep Quick Guide tutorials short and concise, following the Jasc model.

11. Jasc uses a very small font in their Quick Guides. It's equivalent to a font size of -2, which my testers found too small. I opted, instead, for a font size of -1 - a bit easier on the eyes, though still small enough to fit into the Learning Center nicely.

12. Because Quick Guides are not usually printed, but used right within the PSP workspace, color accents are both helpful and effective. I find putting warnings or important notes in RED typeface makes them stand out more readily. That emphasis gets lost when the tutorial is printed in black and white.

Part IV - Using Scripts in Quick Guides

1. If you want to include scripts in your Quick Guides, you should at least be familiar with recording a script. See my Recording a Simple Script in PSP 8 tutorial for ideas on getting started in Script writing. Also, PSP 8 comes with a "Scripting for Script Authors" document, which you can find in the PDF Files folder within the Learning Center folder of the PSP 8 program. This document is called "Scripting HowTo.pdf". A more recent version of this document can be found at the Jasc site HERE.

2. If you include scripts for performing actions, keep them optional.

3. If you are going to include scripts in steps, keep the steps simple, with just a single action per step. Study the Jasc Quick Guides for inspiration!

4. With scripts that invoke dialogs, make dialog steps Interactive so that the user can use the dialog. Once you have recorded the script, open it with PSP's built-in Script Editor and change the Mode to Interactive:
   

   Then, no matter how the user has the Script Playback Toggle set, the dialog will open for user input.

5. With scripts, if you want the colors/materials in the Materials palette to be used, UNcheck the Save Materials box in the Save As dialog:
   

   If you forget to UNcheck the Save Materials box, open the script in a text editor and replace lines looking something like this:

   

   with these lines:

   

6. Many scripts can be edited to remove Tool Options settings. For example, here's a portion of a script to color an image using the Change to Target Brush tool:
   

   When the options highlighted in green are removed:

   

   the resulting script picks up the missing options (Size, Hardness, Density, Rotation, Thickness, Step and Opacity) from user input in the current Tool Options palette. So when the user chooses values different from those you suggest in the Quick Guide, those values will be reflected in the image even if the user lets the script perform the action.

   Note: Some tools, like the Flood Fill tool, don't seem to "refresh" easily. To test different settings with this tool, I have found it necessary to select another tool and then return to the Flood Fill tool to get it to pick up new options. With other tools, like the Change to Target Brush tool, changed options are immediately reflected in repeated applications of the script.

7. The script to "choose a tool for me" is very simple, and I've included it here in its entirety:
   

8. The things that have to be changed in the above script include the Author, Copyright information, Description, and then the tool name, highlighted in pink at the end of the script. This would ordinarily be quite easy, but trying to find what Jasc used for those tool names in the Scripting Command_API is somewhat of a chore. The Jasc techies were not exactly consistent in assigning names to the tools, as you will see. So I've included here a handy dandy quick reference chart of all the PSP 8 Tools, with the associated names needed for scripts:

   Tool Name API Command Name Airbrush Airbrush Background Eraser BackgroundEraser Burn Brush Burn Change to Target Brush ChangeToTarget Clone Brush CloneBrush Color Replacer ColorReplacer Crop Crop Deform RasterDeform Dodge Brush Dodge Dropper Eyedropper Emboss Brush EmbossTool Eraser Eraser Flood Fill Fill Freehand Selection FreehandSelection Hue Brush Hue Lighten/Darken Brush LightenDarken Magic Wand MagicWand Mesh Warp MeshWarping Move Mover Object Selection VectorSelection Paint Brush PaintBrush Pan Pan Pen PenTool Perspective Correction PerspectiveTransform Picture Tube PictureTube Preset Shapes PresetShapes Push Brush PushBrush Saturation Brush Saturation Scratch Remover ScratchRemover Selection Selection Sharpen Brush SharpenBrush Smudge Brush SmudgeBrush Soften Brush SoftenBrush Straighten Straighten Text Text Warp Brush WarpingBrush Zoom Zoom

   You might want to select the above chart and choose File...Print, and in the Print Range panel, choose Selection. Then you'll have the chart handy for when you start writing scripts for your Quick Guides.

9. If a script is run from an unconfigured path, it is treated as Restricted. Therefore, if you create scripts for your Quick Guides that must run Trusted, some changes need to be made on the user's system. Here are some possible solutions:

   1. You can instruct the user, in an early step of the tutorial, to add the Quick Guides folder (or just the folder containing this particular Quick Guide) to the Trusted scripts file folders in File...Preferences...File Locations.

   2. Another way to handle this situation is to include a step instructing the user to move/copy that particular script to a Scripts-Trusted folder, as defined in Preferences, before using it. Then, when you want the user to run the script, have them do so from the Script toolbar directly.

   Of course, if you choose the second method above, you won't be able to use a "Perform this step for me" type execution, as you won't know the name of the folder the user moves/copies the script to, and that folder name is hard-coded in your HTML.

   Note: You might want to advise the user to remove the change made to File Locations when the tutorial is complete. In addition, it is wise to include reasons the script must be run Trusted. Savvy users know the power of Trusted scripts, and deserve to know why a particular script needs to be given that status.

Part V - Once You've Completed the Tutorial . . .

1. The next step is packaging. You need to zip up all the files required for the tutorial, including all the images, scripts, and the file containing the HTML.

2. Set up a Quick Guide page on your website where you offer your Quick Guide tutorials. Be sure to include installation instructions. I've included the download and unzip instructions right on my Quick Guides page - that way the user knows before unzipping where things go.

3. The Quick Guides/Category/Tutorial format is absolutely essential - the Quick Guide will not be visible within the PSP Learning Center if this structure is altered in any way. See Part II - How to Set Up Quick Guides for more information.

4. I've heard some discussion about the feasiblility of creating dual format tutorials - a traditional tutorial done the regular way, with a Quick Guide format included as a downloadable for users wanting to use the Learning Center. Actually, if you create your tutorials following the guidelines in this tutorial, especially the tips regarding text size, page/table width and image sizes, the tutorial will be "Learning Center friendly" as is, and no special download need be provided. The user can install any tutorial into the Learning Center as long as "Save As" has not been disabled (though some are better candidates than others). For a description of the required installation process, see my Adding Tutorials as Quick Guides in PSP 8 tutorial.

5. One last tip - you can also include other items with your Quick Guide for the user, such as brushes, presets, materials (patterns, textures, gradients), etc. You might even want to zip these "goodies" separately, and include the "goodies" zip file as an item within the Quick Guide zip file. Just remember to include instructions early in the tutorial for extracting these items and placing them in the correct folders.

That's it. Hope these ideas get you started using the Learning Center to present your "short, fast tutorials" as Quick Guides!

If you have any problems, comments, or questions, please do not hesitate to Email me.