Re: [dita] What Is A Topic

[Erik Hennum <ehennum@us.ibm.com>]

Hi, Dana:

The API Reference and Java API Reference specializations are in fact available on the Open Toolkit site, but you're not at fault for missing them. You have to go to the "Plug-ins: specializations" section and click on the link for "View older releases from the Plug-ins: specializations package" The current web UI only accomodates 3 plugins, but I understand that can be changed (which is pretty important for the plugin contributors). The Java API depends on the API Reference specialization, by the way.

Anyway, regarding the substance -- there was a fit with existing practice: a JavaDoc description of a method typically stands alone as a highly linked target. In the implementation, the method descriptions were quite convenient to model as topics (the same basic structure applies to both class and method descriptions). Supplementing the API relationships with map-based management of related links (and, one hopes, DITA 1.2 implicit linking based on mentions of keywords and terms) are other good reasons.

But, while method descriptions seem a good fit for topics, they wouldn't work as well as _separate_ topics in the sense of separate files assembled by a map -- largely because the subject matter (a Java class) has a single nesting structure that's a stable unit.


Hoping that's useful,


Erik Hennum
ehennum@us.ibm.com


Dana Spradley <dana.spradley@oracle.com> wrote on 01/02/2007 02:45:56 PM:
>
> Are these specializations available for download from IBM? I don't
> see them in the toolkit.
>
> If I may inquire, what prompted the decision to use nested topics,
> instead of nested sections, in programming class topics to handle
> methods of that class?
>
> As you indicate, they don't really make sense as separate topics.