Well yes Erik, I can see that.
It makes sense that reference topic types might require a richer
assortment of nesting structures that mimic the well-defined
hierarchical arrangement of their subject matter.
Perhaps one could merely deprecate nesting tasks inside tasks, or
concepts inside concepts.
As I recall, minimalist topic orientation was invented to move away
from the highly nested, lengthily belabored discursive structures that
reference material often requires.
On the other hand, I personally might have no objection to a topic that
was only a title, with no elaboration, if we considered doing that to
remove the inconsistencies with maps Eliot has pointed out.
Sometimes the title really does say it all.
--Dana
Erik Hennum wrote:
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.
|