Colored code?

[Geoff Hart <ghart -at- videotron -dot- ca>]

Simon North wonders: <<The tools I am documenting require me to include 
software code. Our editor has color highlighting (red, blue, green), 
which will be familiar to many of you. My manager wants me to use the 
same color highlighting in the documentation (and online help).>>

My first reaction is that it'll be so flashy as to be unusable, but 
that's just me; it's been many years since I programmed (as a rank 
amateur), and preferred my code in black and white, with minimal or no 
highlighting. If the editor your target audience is using follows this 
color convention, then you're doing that audience a favor by relying on 
their learned knowledge: they already know how to interpret the color 
efficiently.

One devil's advocate question: Is the color coding standard and fixed, 
or does each programmer choose their own color preferences? If the 
latter is true, then adhering to an arbitrary color code may do more 
harm than good: it will only be easily comprehensible by those who have 
used the code. Programmers being somewhat independent-minded, I'd wager 
that most have overridden the program defaults and chosen their own 
color coding.

<<I have tried fending it off on the grounds that it would be labor 
intensive to do...>>

If you're using a word processor or Frame, you should be able to define 
the coloring as part of the paragraph style (for entire paragraphs) or 
the character style (for lines and smaller chunks of text such as HTML 
tags). Simply create separate styles for each type of code, and define 
the appropriate font color or highlighting, as the case may be.

<<...not to mention the extra QA work...>>

If your authoring tool has any kind of decent search tool, you can 
search for code snippets based on character patterns that identify 
code--there's usually one or more recurring themes, such as the < > 
tagging in HTML and the ; at the end of lines of Pascal code. By 
searching for these patterns, you can easily find all the text that 
need to have a style applied. If you're a skilled search and replace 
geek, you may even be able to apply all the formatting in a single 
global search and replace.

BTW, this same tip applies for many other kinds of editorial 
consistency, and can save enormous amounts of time.

<<We use discrete colors in the docs and online help, with which the 
bright colors of highlighting are going to clash violently.>>

That's more of a problem. The goal of the color coding is to 
communicate effectively, and if the surrounding colors interfere with 
this communication, then the color coding no longer works effectively. 
One possible compromise might be as follows: in the main help window, 
set the code in the same color as the surrounding text (black ink?), 
but make it clickable to display a popup window that shows the code in 
all its highlighted glory.

This accomplishes two important things: First, it presents the main 
help simply and effectively, while still making the highlighted version 
available for those who will benefit from it. Second, it facilitates QA 
because all popup windows can be formatted consistently using the 
colors that your readers will expect. You could also use screenshots 
for these popups (so the color coding would be automatically applied by 
the code editor without requiring you to apply the format), with the 
main help window holding the identical code sample as text that can be 
copied and pasted into a program for modification by the programmer.

<<My manager wants to press the point and intends to put it out to a 
vote. >>

If the "vote" is actually a survey of the people who will be using the 
docs, this is a good thing: they'll tell you what works well for them. 
But try to do this as an actual investigation of their needs rather 
than as a "vote". You'll get better results if you understand why they 
prefer one approach over another.

--Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


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

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.