[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [platform-doc-dev] Style issues
|
John Arthorne wrote:
I think we should agree on a standard way of referencing actions and
preferences in the doc. About half of the doc uses bold text when
referencing menu actions, and half doesn't. Most of the doc uses the
">" character to separate cascading submenus (for example, File > New >
Project...). I've seen a couple of places that use "/", and some that
use "->". My personal preference is bold text using ">" signs (<b>File
> New > Project...</b>).
Standardization is a very good idea.
Highlighting menu actions is also a good idea, and <b></b> certainly
works. However, you could also use something along the lines of
<span class="menuaction">File > > New > Project</span> if you
wanted to provide more flexibility in the highlighting that you apply.
For preferences, there are again a variety of styles. Some places will
give the full path to get to the preference (Window > Preferences >
Workbench > File Associations), while some will just give the path
within the preference dialog (Workbench > File Associations). Again,
there are a variety of separator styles; some are bold, and some aren't.
Of all these, I like the style used in the platform tips and tricks
document. This style assumes the user knows how to find the preference
dialog, and just gives a parenthetical bold reference to where in the
dialog the preference is found. For example: "There is a preference
(<b>Workbench / File Associations</b>) for choosing which editor to open
for a given file type".
Any thoughts?
It would be nice to think that customers will read at least the Getting
Started section, will work through the tutorials, and will remember
where all the functionality was located. However, in real life there is
always the danger that any online help page will be the first page that
a customer views. For that reason I prefer to make each page as
self-contained as possible. What that means in this case is that I would
always give the full path to the preference page being discussed.
Mike
