Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[stp-dev] Time to think about online help for STP

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 label="Creating services using JAX-WS">
  <link toc="/" />
 <topic label="Translating BPEL to Java">
  <link toc="/org.eclipse.stp.b2j.doc/toc.xml" />
 <topic label="Modeling business processes">
  <link toc="/org.eclipse.stp.bpmn.doc/toc.xml" />
 <topic label="Reference">
   label="STP core API"
   href="" />
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?
David Porter
Senior Technical Writer
IONA Technologies

Back to the top