TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
