Register (free!) to see more.
What is OpenID?
Although online help (either task-based or UI-centric) and API reference documents serve different purposes, there are times when you may want to at least create associations between the two or at most merge them into one system. This may be especially true if your users are programmers or developers who may be accustomed to digging through the API reference as much as any part of the documentation for specific information. In the case of Java documentation the two types of documentation are very separate but integrating them can be done.
In the "surface" (or "shallow") approach, I simply add a link to the Javadocs from the online help's table of contents. JavaHelp allows content providers to seamlessly combine and integrate different helpsets. This is automatic and requires no work by the author (other than to include the sub-helpset).
To add this table of contents entry, simply create a new helpset (for example, api.hs to represent the Javadocs(. Essentially, this new helpset is empty, except for the contents (toc.xml) declaration:
<xml version='1.0' encoding='ISO-8859-1'?>
<toc version="1.0">
<tocitem text="API Reference (Javadoc)" target="link or targeted for the Javadoc" />
</toc>
Then add this as a sub-helpset to your main helpset:
<?xml version='1.0' encoding='ISO-8859-1'?>
<helpset>
<subhelpset location="welcome.hs" />
<subhelpset location="gettingstarted.hs" /> <!-- Getting Started Guide -->
<subhelpset location="userguide.hs" /> <!-- User's Guide -->
<b><subhelpset location="api.hs" /></b> <!-- Javadoc -->
</helpset>
This figure illustrates the "Shallow" method:
Surface.approach
Pros: Very easy to implement, by adding a new to your main helpset file, including the Javadoc as a table of contents item. Requires no coordination between help author and Javadoc author. No maintenance issues.
Cons: No direct relationship between help content and Javadoc — Javadoc appears as a "separate" document.
page: 1/2
