Re: Five points of style, five questions -- responses

Subject: Re: Five points of style, five questions -- responses
From: Odile Sullivan-Tarazi <odile -at- mindspring -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Mon, 6 Nov 2006 10:07:45 -0800


So, I posted those same two questions (on the treatment of directory and file names, and variables in path names or code), along with three others, to two other lists. I received eight responses to the entire set.

Here are those eight questions, with the responses tallied, including the responses on this list to the first two. I thought you all might be interested as well.


Odile



------- The questions

(1)
Do you use a monospace font for directory and file names? Or have
you gone instead to leaving such names in plain text?


plain text -- 1

plain text, bold -- 1

italics -- 2

monospace -- 4

doesn't matter, but monospace is common -- 1

one style for directory and file names, and UI labels -- bold char style


(2)
How do you represent variables, either in code lines or in directory
and file names? Do you use regular italics, an italicized monospace
font, angle brackets, or some combination?

The treatment of (dir and file names -- 1) and (variables in path names or code -- 2) must be considered together, so here are the responses to (2) in conjunction with those of (1).


plain text for (1), angle brackets for (2) -- 1
(monospace only for commands users must type in the command window)

regular font bold for (1), regular italics for (2) -- 1
(previously monospace for [1])

regular font italics for (1), monospace italics for (2) -- 1
(previously angle brackets for [2], but as the code itself began to include angle brackets, the distinction was no longer clear)

regular font italics for (1), angle brackets for (2) -- 1 (with a note that regular italicized text in angle brackets also seems common for [2])
(monospace just for command sequences)

monospace for (1), monospace italics for (2) -- 2

monospace for (1), monospace plus angle brackets for (2) -- 1

monospace for (1), regular italics for (2) -- 1

monospace is common for (1), traditionally italics for (2) -- 1
(with the note that one ought to avoid characters such as angle brackets or quotation marks if the context is such that users might misinterpret these characters as forming part of the content, rather than highlighting it)

bold character style for (1), bold plus italic style for (2) -- 1
(bold plus italics also used for emphasis)


Additional responses, just on (2) --

regular font italics, no angle brackets -- 3


(3)
How do you indicate missing lines in a code snippet? Do you use
three (widely spaced) horizontal ellipsis points or a series of three
vertical ellipsis points? Or do you use some other method altogether?


not applicable -- 2

doesn't come up often, horizontal seems right -- 1

vertical ellipsis -- 2

horizontal ellipsis -- 1

horizontal ellipsis, with blank line above and below works -- 1
(with a note that a comment could also be inserted in the code sample)

comment in code, vertical ellipsis also okay -- 1



(4)
Do you set off the infinitive phrase that leads into a stepped
procedure in any way? If so, in what way?

Note: By this question, I had intended to flush out distinctive treatment such as font change, not simply the colon that traditionally separates intro from steps, but I wasn't clear enough, so many of the responses addressed punctuation. I assume those latter responses indicate, by virtue of omission, the lack of additional distinctive treatment.


infinitive phrase in bold and italics, with additional white space above it -- 1

infinitive phrase in bold sans serif -- 1

no unusual emphasis -- 1

infinitive phrase followed by colon, no other treatment -- 1

infinitive phrase followed by colon, by which I think can be read no additional distinctive treatment -- 4
(with a couple of comments on the issue of fragments vs. full sentences for procedural lead-ins)


(5)
Do you place UI labels in bold? If so, in stepped procedures only?
Or in both procedural and body text? Do all UI labels go in bold or
only some? If only some, what method do you use to determine which
ones? (Only some labels, only following certain verbs?)


bold only in procedures, only to name the direct object of the action (that is, anything the user clicks, opens, or types) -- 1

bold only to name the direct object of the action -- 1
(and so, quite possibly only in procedures)

bold throughout the doc -- 1
(and so, quite possibly in running text as well as in procedures)

no font change, initial caps only, but bold allowed if presentation is rendered clearer by it -- 1

no font change, initial caps only -- 2
(with, in one case, this style applying across several clients)

style varies considerably across clients -- bold used often when the label indicates user entry in procedures, but plain text is more common in descriptive and introductory paragraphs -- 1
(with a note that clients often begin by highlighting labels liberally, only to find that too much appears then in bold, so they rethink the guidelines, scaling back on the bold, until someone comes along to set the whole cycle in motion again)

be consistent, be clear, personal recommendation is to avoid boldface in running text, with a note that italics is less intrusive and can work well -- 1
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Previous by Author: Monospace font or not for directory and file names
Next by Author: RE: TECHWR-L Digest, Vol 13, Issue 27
Previous by Thread: RE: Coordinating Field Defs and Procedural Info
Next by Thread: Simple editing - willingness versus competence


What this post helpful? Share it with friends and colleagues:


Sponsored Ads