|
|
The IDE Help Indexing Guidelines are for use by all writers that contribute help sets to the IDE. The purpose of the guidelines is to help ensure that the merged indexes from the various helpsets are consistent and coherent. Following the guidelines in this document helps to prevent the problems identified in the Merged Index Project Plan.
This is a preliminary draft that is a work in progress. It needs to be reviewed by the editors as well as the Help Style Team. It also needs to be reviewed by CDP writers, JETS team members, Compiler Collection writers, and internal third-party writers. Also, we have not completed the rules for indexing context-sensitive help.
This is a living document. Please contact the merged index tiger team via the MITT@Sun.Com alias if you have questions, if you wish to request additions, deletions, or changes, or if you are having problems using the guidelines.
If you want to be notified about updates to the guidelines, subscribe to the MITT-interest@Sun.Com list using the Net Admin tool (alias will be available 10/31/03).
Note: In these guidelines, the + symbol indicates a group entry and the - symbol indicates a non-group entry (an entry with an actual target).
You can prevent many common merged index problems by following the Indexing guidelines in the Sun Editorial Style Guide. In particular, follow these rules:
Due to the constraints imposed by JavaHelp and general online help indexing guidelines, please follow these exceptions to the ESG indexing guidelines.
+ compiling
+ JSP files
- about
+ containers
This rule is to enable you to use the common groupings. For more information, see 3. Use the Global Groupings List When Creating Grouping Entries
- bundles, resource, See properties files
Instead, do the following:
+ bundles, resource
- (See properties files)
All entries with (See) subentries are double posted. The [dp] key indicates that the entry is a double-posted multiple-word entry. The following excerpts from the Global Groups List show examples of double-posted entries:
CCI (common client interfaces) [dp] Explorer window Runtime tab [dp] extensible markup language (See XML (extensible markup language)) interfaces (See CCI (common client interfaces)) Runtime tab, Explorer (See Explorer window, Runtime tab) XML (extensible markup language)
When you create index entries that are not on the global list, follow the ESG rules in regards to double posting.
When you add an entry to your index, think how helpful the entry will be when merged with the other help sets. For example, in the JSP help set, the following entries make sense in the context of JSPs:
- breakpoints, about - correcting source code
When viewed in the merged index, the users will probably assume that these entries apply to Java code or C++ code and will be disappointed when they bring up the target topic. These entries need to be qualified as shown in the following example:
+ breakpoints
- enabling and disabling
+ JSP
- about
- properties, modifying
- removing
+ source code
- formatting
- guarded text in
+ JSP
- correcting
Be careful about ambiguous terms. For example, in the following entries, will the user know that these point to Form Editor topics and are not about adding Web components?
+ components - adding - copying
When indexing an ambiguous term, check the Global Index Groups list first to see if there's a recommended way to deal with the ambiguous term. See "3. Use the Global Index Groups List When Creating Grouping Entries" for more information.
When you add an index group (a primary entry with secondary entries or a secondary entry with tertiary entries) try to choose an index group from the Global Index Groups list. If you cannot find an entry in this list that meets your needs, try to create a grouping that fits in with the list.
If there is an applicable common grouping, always use the grouping, even if you have only one entry. Say, for example, you have an index entry of "compiling JSP files". The common groupings list shows the following groupings:
+ compiling
+ JSP files
+ Java classes
+ MIDlets and MIDlet suites
Because there is a grouping for compiling JSP files, you must create a "compiling" primary entry, create a "JSP files" secondary entry, and add a single tertiary entry, such as "about".
The reason for this rule is to ensure that your entry is merged with other entries for the same group. If you do not follow this rule, the merged index could look like the following example. The first entry would be from your help set.
- compiling JSP files
+ compiling
+ JSP files
- Ant, using
- compiler, specifying the external
+ Java classes
...
+ MIDlets and MIDlet suites
...
Note: If there is a group entry in the Global Index Groups list for which you have only one topic, and you are absolutely sure that no other help sets will be placing index entries under that group, you may change the group to a single entry with a target. If you do so, remember to check that entry in the merged index before full customer ship to ensure that the entry does not require a group. Please notify the MITT@Sun.COM alias about the change.
Primary index entries that have secondary entries and secondary entries have tertiary entries cannot have targets. The reason for this rule is because the Help Viewer will not merge index entries that match in text but do not have matching targets. For example, consider the following entries from different help sets.
Help Set 1
<indexitem text="code completion">
<indexitem text="automatic completion, disabling"></indexitem>
<indexitem text="database, updating"></indexitem>
</indexitem>
Help Set 2
<indexitem text="code completion" target="aboutcodecompletion">
<indexitem text="XML documents, for"></indexitem>
</indexitem>
When merged, the index entries will appear as such:
+ code completion
- automatic completion, disabling
- database, updating
+ code completion
- XML documents, for
In this situation, the second help set should remove the target from the primary entry and add a secondary "about" entry so that the merged index looks like the following example:
+ code completion
- about
- automatic completion, disabling
- database, updating
- XML documents, for
Do not use index entries for separators, such as entries without text or entries with text set to "====".
See and See Also entries must be indexed as single secondary entries or single tertiery entries. For example:
+ commands
+ IDE menu
- (See menu items, IDE)
+ compiler types
- (See also compilation settings)
+ indirect
+ javac
+ database parser
- (See code completion)
Do not have entries like the following example:
Wrong - database parser, See code completion
See and See Also entries must be wrapped in parentheses. This rule is to ensure that these entries sort to the top. Here is an example of See and See Also entries.
+ application servers - (See also Sun ONE Application Server 7) - (See also Sun ONE Web Server) - (See also Tomcat Web Server) - default server, setting - nodes in the Runtime tab - server instances + archive files - (See EAR (enterprise application archive) files) - (See JAR (Java archive) files) - (See WAR (web archive) files)
See the Indexing chapter in the ESG for information about when to use See and See also entries.
Do not create primary index entries for general terms such as the following:
Invalid Primary Entries adding xxx creating xxx customizing xxx deleting xxx developing xxx dialog boxes importing xxx preferences using xxx opening xxx removing xxx
Do not create primary index entries for every property name and menu items. Index by property name only if you think the users will have a need to read about the property and will know the property's name. For example, the following entries should not be primary entries.
Wrong - Add to Project menu item - Add Newline Before Brace property - Add Space Before Parentheses property - Edit menu
Instead, you might want to create the following entries:
OK
+ keyboard shortcuts
- Edit menu
+ menus
+ IDE, shortcuts
- (See keyboard shortcuts)
+ projects
+ components
- adding
+ Source Editor
- newline before brace setting
- space before parenthesis setting
If you believe that it is necessary to index the property name, ensure that you provide enough of a qualifier so that the user knows what task the property applies to. For example, use "Abbreviations property, Source Editor" and not simply "Abbreviations property".
Wrong
- Abbreviations property
- Event Variable Name property
Suggested System-Oriented Entries
- Abbreviations property, Source Editor
- Event Variable Name property, Form Editor
Suggested Task-Oriented Entries
+ event handlers
- event variable name, specifying
+ Source Editor
+ abbreviations, expanding
- creating and modifying
Do not create primary index entries for every property sheet and property editor. Be especially cautious when adding an entry for a sheet or editor with an ambiguous title such as "name" or with no title at all.
Consider creating index entries for tasks and actions for which the users would use the property editors and sheets, instead of creating entries for the sheet's name or the editor's name. For example, the following entries are not very helpful.
Wrong
Root Offset property editor
Installation property sheet
OK
+ Javadoc documentation
- specifying top-level directory
+ Tomcat servlet container
- installation settings
Remember that help topics for for property sheets and editors are accessible through the Help buttons and that it is more likely that the users will use the Help button to access help rather than the Help window's index.
Do not create primary index entries for dialog boxes. Dialog boxes are associated with creating and customizing things. Therefore, the index entries for topics about dialog boxes should be secondary "creating" and "customizing" entries
Create primary entries for all major objects. For a definition of object, see "Filesystems and Objects" in the core online help. Examples of objects are Java source files, enterprise beans, JavaServer Pages, servlets, and WAR files.
Create primary entries for all wizards and for the major components of the GUI, such as the following windows:
Debugger window Explorer window Form window main window Options window Output window Properties window Source Editor
When indexing an object, include all of the secondary entries in the following list that are appropriate for the object. If A [dp] follows the item, then there is a primary bucket for that term. If that term is appropriate for your object, put the index entries in the primary bucket. Then, either fully index under the object or add a (See) that points to the appropriate item in the primary bucket. For example:
+ debugging
+ JSP files
- watching variables and expressions
- viewing generated servlet
+
+ JSP (JavaServer Pages)
+ debugging
(See debugging, JSP files)
or
+ debugging
+ JSP files
- watching variables and expressions
- viewing generated servlet
+
+ JSP (JavaServer Pages)
+ debugging
- watching variables and expressions
- viewing generated servlet
Common Secondary Entries
adding (such as adding a MIDlet to a suite)
compiling [dp]
configuring
creating
customizing
debugging [dp]
deleting (the opposite of creating)
disabling
editing [dp]
generating
importing [dp]
node in Explorer
(or by name, for example:
enterprise beans
Included EJB node
opening
packaging
projects [dp]
properties
removing (the opposite of adding)
running [dp]
testing [dp]
validating [dp]
wizard
The following entries are optional secondary entries for specific types
of objects:
XXX archive files
deployment descriptor for [dp]
XXX
running
in a specific locale
in the debugger
passing arguments
setting runtime options
specifying an executor
XXX applications
overview
architecture
tools overview
creating
importing [dp]
exporting
configuring
assembling
deploying
clients