Documentation Team Workflow

Documentation teams should refer to the product’s architectural specifications to define an appropriate architecture (that is, granularity, content partitioning, plug-in naming, and so on) for online documentation plug-ins. With that information, Documentation teams can begin the process to create context-sensitive help plug-ins.

The Documentation team workflow described in this section assumes that dedicated context-sensitive help plug-ins will be produced from DITA-XML map documents. The workflow can be adjusted for other help content source formats.

The following list summarizes the overall Documentation team workflow to create context-sensitive help plug-ins:

Get the helpKey list (provided as a Java source file) from the UI Development team for each UI plug-in.
Analyze the helpKey list and associated UI controls to define the help contexts. (For more information, see Defining Help Context IDs.)
The Documentation team must determine whether:
- The helpKey constants alone are sufficient to identify actual help contexts, and thus, helpKey constants could map directly to a concrete help context ID, with the same string value as the helpKey constant.
- Distinct help context ID strings must be defined to combine groups of helpKey constants into common help contexts.
Tip: It may be preferable to combine help contexts in the helpKey properties file, instead of defining the mapping for multiple help contexts to a single topic in a DITA map. This is a judgment call for the Documentation team lead, and the IAs responsible for maintaining DITA maps.
Analyze the help contexts and existing (or planned) help topics to define context-specific help search expressions.
Create helpKey properties files, based on the content of each Java source file.
- Define the mapping of helpKey constants to concrete help context IDs and context-specific help search expressions, based on results of the help context analysis and help topic (content) analysis.
- Save the helpKey properties files in source control, as appropriate.
Tip: The helpKey properties files are flat ASCII text files, so the authors (or IAs) responsible for defining the help context IDs and context-specific help search expressions should use a suitable ASCII text editor to create and edit those files.
Modify existing DITA maps (if used to produce online documentation plug-ins) to add the markup for context-sensitive help.
Test the deployable context-sensitive help plug-ins, with UI components provided by Development teams.

Help Context IDs
Because helpKey constants are abstract entities in the Java code, and independent of the actual help context IDs, Documentation teams are responsible for defining the help contexts, which the Eclipse help system uses to locate context-specific help content, and associating each helpKey constant with an actual help context ID.
Help Search Expressions
Each help context should be associated with a context-specific help search expression, which the Eclipse help system will use to provide Dynamic Help search results in the Help view.
Context-Sensitive Help Plug-ins with DITA
Any DITA map document that defines an online documentation (doc) plug-in can be modified to also define a corresponding context-sensitive help plug-in by inserting the appropriate context-related markup.