Tutorial without final data (%, $)?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Ruby Isaacs reports: <<My client has asked me to include a lengthy example,
which includes many features, in the online help. Initially I thought of
this example as a basic tutorial. However, while the interface for the
Web-based tool will not change, the data in terms of percentages and dollar
figures shown in the charts and tables will change. How can I create a basic
tutorial that does not include the correct data that the user will see if
they complete the tutorial correctly?>>

It's not clear what the real problem is here; if it's just an example, it
doesn't matter what numbers you use provided that the results of the
calculations are correct, that the tutorial clearly demonstrates the logic
used by the software or the user trying to solve the problem, and that the
approach is clear.

If you mean that the software displays data that guides the user through the
example, and that the guiding data will change, then sample calculations in
the tutorial that are valid now will be invalid in 1 month. Your problem
becomes one of writing the example to work well with current numbers, then
substituting the final numbers at the last possible minute (once the
interface is frozen.) Of course, persuading them to freeze the numbers used
as the basis for calculations right now would make your life easier, but
that's not always possible:

<<If I insert charts or tables that will not be included in the final
release of the software, I think the user will think that they've completed
the tutorial incorrectly.>>

That's more of a problem. You said that the interface won't change, but this
statement contradicts that. If you have any strong suspicion that the
interface will change in such a way that your example becomes obsolete, you
need to raise this problem with the development manager and come to a
solution that meets both your needs.

Of course, sometimes you'll just have to accept that your example is
conceptually correct and useful for demonstrating the overall idea, even if
it no longer matches the software. A while back, I shipped a tutorial that
made careful reference to the locations of the files used in the tutorial,
only to discover that despite agreeing to freeze the names and locations of
these files, the developers changed them at the last minute before burning
the CD. Welcome to the life of a techwhirler!

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada 
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FrameMaker-to-PDF TimeSavers Assistants let you enhance & automate navigation
in PDF doc sets (chapter tabs, next/prev chapter/pg, bookmarks, popup menus);
create interactive PDF forms, rollover popups; presentations: http://www.microtype.com

Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever! http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.