Re: Colored Code
Oh, the joys of having a micromanager.
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.
Yes. Very helpful when working in code.
My manager wants me to use the same color highlighting
in the documentation (and online help).
You're including code snippets in doc and help? That implies you are doing technical doc for developers, right? I mean you wouldn't include code in doc for consumers; so I assume your end users are developers, who are familiar with the concept of color coding.
I have tried fending it off on the grounds that it would be labor
intensive to do (not to mention the extra QA work),
Not all that labor intensive. Use the tools you have, namely the code editor where the coloration is already taken care of.
Here's one way: Print a page of code to a PDF. Open the PDF in an editor (Illustrator or Acrobat, for example) and delete the portions of the page you don't need for the example you are working on. Save as an EPS and place in your doc. Save as a GIF for your online help.
This means, of course, that the text will not be available for copying in the online help. So here's another approach: Copy the code from the editor and paste into Word. Are the colors preserved? If so, save as "simple HTML" (that's an optionally installed File menu command in some versions of Word--YMMV). This should preserve the colors. Open the HTML code and copy out the relevant section. You may have to copy portions of the stylesheet, too; but you should only have to do that once.
This is more labor-intensive (using either method) than having plain black code, but it is less labor-intensive than manually changing colors throughout.
though I also
consider it ugly and amateur.
I'm not sure your esthetic judgment carries much weight here, if your boss's consideration is that the coloration provides value to the end user.
We use discrete colors in the docs and
online help, with which the bright colors of highlighting are going to
clash violently.
I assume you mean discreet (as in muted) colors. My guess is that you can find a dialog somewhere in your code editor that allows you to specify the colors to be used in the interface. Make them match your document palette, at least in terms of hue. (Making them match in saturation might cause legibility problems.)
In the online help, I think it will be a major
distraction. Generally, I'm afraid the docs are going to look like an
infant was let loose with a pot of paints.
It doesn't have to if done well.
My manager wants to press
the point and intends to put it out to a vote.
I think your major argument is that it will take longer to create the docs and more effort to maintain them in the future.
Please, can you give me a peer vote? Am I being pedantic, or would you
support my stance? Help!!!
If you want to reduce this to majority rule, the thing to do is bookmark a bunch of online sites that offer instruction in programming languages (javascript freeware sites, MSDN, academic sites, etc.). Then bring your boss over to your workstation and show him that 100 out of 100 such sites, including the big kahuna, Microsoft, do not go to the trouble he is asking you to go to but just show the code monochrome. Maybe he'll settle for a monochrome other than black, as a compromise, maybe a nice brown from your palette, for example.
Simon North
I won't mention the company name ...
But its initials are QCL, I take it?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
References:
Colored Code: From: Simon North
Previous by Author:
Re: Writing tests for Peoplesoft contract position?
Next by Author:
Re: Colored Code
Previous by Thread:
Re: Colored Code
Next by Thread:
RE: Colored Code
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads