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.
I'd like to kick this in for discussion. In one of the projects I'm working
on, we provide (currently 8) code examples/templates. What I did for the
beta release was comment the code heavily, mark each comment, and refer to
the comments from the documentation. Now "Ma" below has suggested another
way of doing it (my response is below) and I really am not sure whether I'm
for or against it. On the one hand, it would certainly make that chapter of
the manual easier reading - no flipping back and forth between manual and
code - on the other, well, see my response under "Me".
Ma:
>Also, I'd like to reduce the number of references to comments in the code
>and place more of the explanation in the document. It is useful having
>specific references out to the code (e.g. see C20) but I want to be able to
>read everything in one place. It might also be useful to occasionally bring
>some of the code in the helloworld examples into the document (as we have
>for IDB examples) and discuss within the document.
>What do you think?
Me:
>I'm not agin it - though the two advantages of having the comments/the code
referenced
>in the manual, but not repeated, are that it makes it simpler to keep the
code
>consistently updated and that it forces people reading the manual to go
look at the
>examples.
*** 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
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
---
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.
