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.
Subject:Re: Boxes for Code, Screens? From:"Jeanne A. E. DeVoto" <jaed -at- jaedworks -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Mon, 15 May 2000 17:40:03 -0700
At 10:30 AM -0700 5/15/2000, Janice Gelb wrote:
>We are currently engaged in a discussion at Sun about
>whether to put boxes around code examples or screen input/
>output listings. Opinions vary as to whether programmers
>or system administrators like or expect boxes, or
>whether just using an alternate font and indenting
>is enough of an indicator.
It seems to me this is an issue of book design rather than style. In other
words, do the indenting and the monospace font set off examples and
listings clearly enough, visually, so that they can be distinguished at a
glance? The answer to this is going to depend on such questions as "How
much indentation, exactly?" and "Which fonts are being used for body and
code, and do they contrast well with each other?" - things that are
specific to other aspects of your book design.
On the one hand, boxes are ugly. On the other, they let the reader take one
look at a page and see immediately whether it contains a code listing and
how long it is.
One compromise I've seen is to put a light gray screen behind code
listings, giving the effect of a boxed listing without using heavy black
borders which break up the page visually.
