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