Hi
I just wanted to point out that the initial
commit of the Service Creation subproject included an online help plug-in,
org.eclipse.stp.doc. This focuses solely on service creation at the
moment, but is structured so as to allow the inclusion of help on other STP
subprojects.
I'm proposing that we
centralize our documentation effort under the org.eclipse.stp.doc plug-in. For
example, we could add the STP Core Javadoc and some of the BPEL to Java documentation in
there right now.
As part of this, I'd like to move the org.eclipse.stp.doc plugin out
from under the Service Creation subproject. I then propose creating separate
doc plug-ins within each subproject. The table of contents in the
top level plug-in would then point to TOCs in each of the subprojects, like
this (these are just working titles):
<toc label="SOA Tools Platform Developer
Guide">
<topic label="Building SOA
networks">
<link toc="/org.eclipse.stp.soas.doc/toc.xml"
/>
</topic>
<topic label="Creating services
using JAX-WS">
<link
toc="/org.eclipse.stp.sc.doc/toc.xml"
/>
</topic>
<topic label="Translating BPEL to
Java">
<link toc="/org.eclipse.stp.b2j.doc/toc.xml"
/>
</topic>
<topic label="Modeling business
processes">
<link toc="/org.eclipse.stp.bpmn.doc/toc.xml"
/>
</topic>
<topic
label="Reference">
<topic
label="STP
core API"
href="" />
</topic>
</toc>
One other thing:
the help is currently written as Docbook XML and transformed into the
Eclipse plug-in format using XSLT. However, I'm not particularly wedded to
Docbook. In fact, the more I think about it,
the more I'd rather just source it in HTML and edit the toc.xml by hand.
It would be good to get a discussion going on what the appropriate
source format for the documentation should
be.
Does anyone have any thoughts
on this?
Thanks
David
Porter
Senior Technical
Writer
IONA
Technologies
