Tutorial Writing CMPE 285

First, choose your subject matter A software application. A software application. A piece of hardware. A piece of hardware. A technique or process. A technique or process. Whatever you choose, choose something you know well. Whatever you choose, choose something you know well. You may want to choose a particular task (or small set of tasks) instead of creating a comprehensive tutorial: You may want to choose a particular task (or small set of tasks) instead of creating a comprehensive tutorial: Creating graphs from Excel data. Creating graphs from Excel data. A guide to the new features available for Photoshop CS3. A guide to the new features available for Photoshop CS3.

Introduction What is this tool for? What is this tool for? What type of user is this tutorial designed for? What type of user is this tutorial designed for? A novice to the general subject? A novice to the general subject? Example: The Freshman Biology Student’s guide to the Human Genome Browser. Example: The Freshman Biology Student’s guide to the Human Genome Browser. Someone knowledgeable in the general field, but a newcomer to the tool? Someone knowledgeable in the general field, but a newcomer to the tool? Example: LaTeX for the MS Word user. Example: LaTeX for the MS Word user. A regular user of the tool, who may benefit from seeing examples of certain features? A regular user of the tool, who may benefit from seeing examples of certain features? Example: Designing Realistic Human Faces using Maya Animation Software Example: Designing Realistic Human Faces using Maya Animation Software

Tutorial Style Be aware of your tutorial’s likely use: Be aware of your tutorial’s likely use: Will this be read in a linear fashion? Will this be read in a linear fashion? Will the user simply glance through your tutorial, looking for relevant information? Will the user simply glance through your tutorial, looking for relevant information? Is it easy to find quick answers? Is it easy to find quick answers? Are headers and illustrations obvious without explanation? Are headers and illustrations obvious without explanation? Is information on Page 6 incomprehensible or misleading without information on Page 2? Is information on Page 6 incomprehensible or misleading without information on Page 2? If so, do you refer back to this information? If so, do you refer back to this information? Would a table of contents or index be valuable? Would a table of contents or index be valuable?

Tutorial Discussion Start by demonstrating simple tasks. Start by demonstrating simple tasks. Show how simple tasks can be combined to accomplish more complex tasks. Show how simple tasks can be combined to accomplish more complex tasks. Strongly recommended: Strongly recommended: Real-world examples Real-world examples Screenshots Screenshots Photos/Illustrations Photos/Illustrations

End Material/Conclusion There is no one correct approach, but useful approaches include: There is no one correct approach, but useful approaches include: Troubleshooting Guides for common problems. Troubleshooting Guides for common problems. Glossary of useful terms. Glossary of useful terms. Resources for further study. Resources for further study. Conclusions to tutorials are often friendly and content free. Conclusions to tutorials are often friendly and content free. “So now you know how to use Cascading Style Sheets! Have fun!” “So now you know how to use Cascading Style Sheets! Have fun!” Since this often remains unread, especially in non-linear documents, this is acceptable – as long as you cover all your content elsewhere. Since this often remains unread, especially in non-linear documents, this is acceptable – as long as you cover all your content elsewhere. You do need some sort of conclusion, just to indicate and end to the document. You do need some sort of conclusion, just to indicate and end to the document.

Length of Tutorial Can vary widely. Can vary widely. Bullet point lists. Bullet point lists. Figures/Illustrations. Figures/Illustrations. Practical Examples. Practical Examples. … these all take up a lot of space, but are tremendously useful. … these all take up a lot of space, but are tremendously useful. General guideline: 6-8 pages if light on text, 3-5 pages if text-heavy. General guideline: 6-8 pages if light on text, 3-5 pages if text-heavy.