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

[Odile Sullivan-Tarazi <odile -at- mindspring -dot- com>]

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.