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.
As part of the documentation, we're shipping a number of templates/working
examples: real code, compilable, heavily commented (by yours truly) and
referenced in the manuals. This was initially my idea, but has since been
heartily adopted by my manager (I'm part of the development team, working as
a sole technical writer) who ended up writing the code for the examples. I'm
not yet a very good Java programmer, and while I can proofread Java code I
can't write it to the contractual standards required for these examples.
Problem... er.. well... Enthusiastically, my manager's written 7 examples.
Count 'em. Seven. 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. (We're
expecting that a number of users will simply take the final example and use
it as a template for their code.) 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. I think that people working through the examples (which I hope at
least some of our users *will*) are more likely to work through three
examples, whereas they may not even start if they see seven to get through,
and I don't think they're likely to be phased (it's *aimed* at Java
programmers) by the fact that they're expected to take in, in the same
example, that we're now translating text *and* we're ooble-boogling the
dingbat instead of just goobling the batding. (Sorry, my security program
intervened and substituted technobabble for an actual example.)
Am I right about the number of examples? (I think I am, but am willing to
listen to cogently-reasoned disagreement.) If so, what's a nicely diplomatic
way of saying to my boss "Wonderful, but wrong!" (The code looks good, from
my perspective: makes it easy to rewrite, ahem, heavily edit the comments.)
Jane Carnall
Technical Writer, Digital Bridges, Scotland
*** 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.
