Version: <version number> |
Date: <date> |
· Overview
· Step One
· Step X
· Example
· Summary
Provide the objectives of your tutorial. For example, “This tutorial provides the reader with the steps to use extension point… This extension point provides… You may want to use this when… etc.”
Provide references to any other tutorials that may supplement to your tutorial. You are also encouraged to refer the reader to a specific example in the Example section of the Developers Guide.
Describe the approach (including the steps required) that is used in your
tutorial to achieve the objects of your tutorial. For example, “In this tutorial we will
create a WidgetService and WidgetProviders
to demonstrate
Rename the section titles to something more meaningful - for example, “Creating the WidgetService”.
Using text, code snippets and pictures to describe the steps in your tutorial.
Important notices, warnings, or "gotchas" can be highlighted via the "notabene" paragraph style:
Note: Put some important information in here.
Got a question to pose to reviewers? The "question" style provides a consistent look-and-feel:
Question: Put a question to the reviewers in here.
Keep the number of steps in your tutorial to a reasonable number. (<10?)
Keep the length of a particular step reasonable as well - the read may get lost in the details and lose sight of the objective.
The "snippet" style on a <pre>
block provides a nice option for displaying code snippets:
public void run(IAction action) {
CreateTechnicalNoteWizard wizard = new CreateTechnicalNoteWizard();
wizard.init(workbench, selection);
new WizardDialog(window.getShell(), wizard).open();
IFile resultFile = wizard.getResultFile();
if (resultFile != null && resultFile.exists()) {
openEditor(resultFile);
}
}
HTML tables are an alternative that supports captions, but require manual control of the formatting and colour inside the table cell:
Example action delegate run( ) method |
public void run(IAction action) { CreateTechnicalNoteWizard wizard = new CreateTechnicalNoteWizard(); wizard.init(workbench, selection); new WizardDialog(window.getShell(), wizard).open(); IFile resultFile = wizard.getResultFile(); if (resultFile != null && resultFile.exists()) { openEditor(resultFile); } } |
Provide links to source files that referenced in the tutorial steps.
Review the steps in your tutorial against the objects set-out in the overview. Point the reader to examples/samples or further recommended reading.
Copyright (c) 2000,2005 IBM Corporation and others. All Rights Reserved.