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:
  1. Get the helpKey list (provided as a Java source file) from the UI Development team for each UI plug-in.
  2. 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.
  3. Analyze the help contexts and existing (or planned) help topics to define context-specific help search expressions.
  4. 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.
  5. Modify existing DITA maps (if used to produce online documentation plug-ins) to add the markup for context-sensitive help.
  6. Test the deployable context-sensitive help plug-ins, with UI components provided by Development teams.