RE: [platform-doc-dev] Style issues

["John Arthorne" <John_Arthorne@xxxxxxxxxx>]

So in the interest of being explicit in the user doc, we might as well stick to the same convention for preferences as we do for actions.  That is, fully qualifying the path to the preference dialog along with the preference page (<b>Window > Preferences > Workbench > File Associations</b>).  This seems to be the most common format anyway, so it would require the least change to accomodate it.

"Susan Franklin" <susan@xxxxxxxxxxxxx> Sent by: platform-doc-dev-admin@xxxxxxxxxxx 03/18/2003 11:53 AM Please respond to platform-doc-dev

To:        <platform-doc-dev@xxxxxxxxxxx>         cc:                 Subject:        RE: [platform-doc-dev] Style issues

I like the suggestion to standardize on ">" for cascading menus.  I understand Mike's points about semantic styles but during the current push I can't see going back and fixing this now.  I'll continue to use <b> and ">" for now unless someone tells me otherwise.
 
How about a compromise on preferences...
I think that the "getting started" should be as explicit as possible.  And I see Mike's point about a new user encountering any page as their first impression.
 
How about standardizing on John's suggested technique in ISV/programmer doc.  If someone is coding to the platform, then they know where the preferences dialog is.  I'll stick to this for anything new I put in the ISV doc, but can't promise to go back and hit all the old references while content is still the priority...
 
susan
-----Original Message-----
From: platform-doc-dev-admin@xxxxxxxxxxx [mailto:platform-doc-dev-admin@xxxxxxxxxxx]On Behalf Of John Arthorne
Sent: Tuesday, March 18, 2003 7:56 AM
To: platform-doc-dev@xxxxxxxxxxx
Subject: [platform-doc-dev] Style issues


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 &gt; New &gt; Project...</b>). 

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?