Diplomacy/templates problem?

Subject: Diplomacy/templates problem?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 30 Jul 2001 08:47:06 -0400

Jane Carnall reports: <<... we're shipping a number of templates/working
examples: real code, compilable, heavily commented (by yours truly) and
referenced in the manuals... my manager's written 7 examples... One new
concept per example. The idea was to start off with a dead simple example
for newbies, work up to a more complex example. But even the end example
(deliberately) isn't *that* complicated... I think that we ought to meld
several examples together - introduce two or three new concepts per example
- and bring the number down to 3, making the final version a little bit more
complex.>>

Sounds like a good compromise approach: take what your manager has written
and stitch it into a couple smaller modules. That way, you've preserved his
work, yet accomplished your goal of making the examples more challenging and
relevant to the readers, while simultaneously reducing their number. One way
to sell him on this approach is to point out that programming is more than
just creating a series of independant modules: it also involves linking them
and making them coexist happily. If you're lucky, you can find groups of
examples that work well together, and do more than just present examples;
you can also teach the programmer how to program.

<<Am I right about the number of examples?>>

No idea. If you're working with programmers, ask _them_ what _they_ consider
to be an appropriate number of examples. This will also make your approach
much easier to sell to your manager: "while you and I may disagree on the
best approach, we're writing this for programmers, and here's what they
would prefer..."

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

---
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.


Previous by Author: RE: Evaluating Technical Accuracyof User Guides/Online Help
Next by Author: Vector graphics?
Previous by Thread: FW: HATs for context-sensitive help?
Next by Thread: RE: Vector Graphics


What this post helpful? Share it with friends and colleagues:


Sponsored Ads