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 still am unsure of what you mean by "highlighting," but if I assume it
> to mean, as is common in many code editors,
comments are one colour, keywords another, parameters and arguments another, and
so on.
>The Deitel book series,
Interesting. I've been one of the technical editors for the Deitel books for several years
(Java, JavaScript, C, C++, C#, Perl, XML, and a few other languages). The Deitels use
exactly the signaling that I am talking about. In a typical HTML code example, HTML tags
are dark blue, HTML tag content (text) is black, most JavaScript code is black but
keywords are dark blue, HTML tag attribute values are light blue, comments are green,
errors or points of interest are shown in red. All this is printed on a pale yellow
background. I've always found the presentation unnecessarily fussy and sometimes really
confusing. Aesthetically, well I guess that's a matter of taste. However, I would dread to
imagine how much time it takes to markup that code .. and they have a lot more
manpower than just me trying to document six or seven major software tools and a
complete proprietory programming language as well as a complete set of classes,
methods and functions for modeling business logic and developing GUIs. I'm not
complaining about the workload, but it does mean I have to stay focused on essentials.
And this kind of 'enhancement' is something I can do without.
> One advantage of color codign code samples is that the pattern of color
> in the sample will match the pattern of color users will see on the
Only in the editor and only when they explicitly turn it on.
> screen when they create similar code.
... but that's the key. The cognitive loads for editing and comprehension are different. You
could draw a loose analogy to the difference between doing a substantive edit and spell
checking. For code comprehension (not editing), indentation and spacing seem to be the
key features. Color draws attention to detail (which is good for editing) but is a distraction
when you are trying to get the 'bigger picture' .
> One additional thing I didn't see mentioned: If you're actually going to
> take the now-rare step of printing and distributing real books yourself,
No way; I leave my publisher to do that .. in this context we're talking about my day job as
a full-time tech writer, not me wearing my other hat as a computer book author.
> Add to this that even if you're not printing books yourself, but are
> distributing PDF files, the vast majority of business printers are
> monochrome, so a carefully constructed color scheme simply won't show
> up, and some colors might print too faintly to easily read.
Good point, and one I will use. Thank you.
> Finally, if you were to have to create color codign in your documents,
> the best and easiest way to do it would be to set up semantically useful
> character styles (for example, "tag attribute" rather than "green"),
> then assign those styles to mnemonic key combinations.
You may be preaching to the choir here. As an SGML crusader, HyTime fanatic, and
(putting false modesty aside) XML guru, I would be the first to denounce non-semantic
markup.
ROBOHELP X5 - SEE THE ALL NEW ROBOHELP X5 IN ACTION!
RoboHelp X5 is a giant leap forward in Help authoring technology, featuring all new Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more! View an online demo: http://www.macromedia.com/go/techwrldemo
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
