Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [stp-dev] Time to think about online help for STP 
Hi Everyone,
One thing to think about at this point is that the current HTML help systems in Eclipse are incredibly difficult to "upgrade" in commercial products to support use cases which require a combination of project plugins and commercial plugins, and even harder to upgrade to support use cases requiring combinations of project plug-ins and sets of commercial plugins from multiple (or even the same) vendors. The problem is that the granularity of structure in the help documentation doesn't match the granularity of the plug-in extensions that can be made in the software.
What ends up happening is that a "product" is typically shipped with a combination of the vanilla project documentation and a special doc plugin which relates to the use cases supported by that product and which will usually duplicates much of the project documentation.
We are not alone with this problem, but it could do with airing at this stage. Actually it has nothing to do with commercial vs. non-commercial it's just a generic extensibility problem that is more acute in the case of commercial plugins. 


Mike

Johnson Ma wrote:

Hi David,
I think the HTML format is good. I checked those doc for pde and wtp projects in CVS . They are all using HTML format directly. Johnson 

    ----- Original Message -----
    *From:* Porter, David <mailto:David.Porter@xxxxxxxx>
    *To:* stp-dev@xxxxxxxxxxx <mailto:stp-dev@xxxxxxxxxxx>
    *Sent:* Tuesday, October 17, 2006 6:19 PM
    *Subject:* [stp-dev] Time to think about online help for STP

    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="/org.eclipse.stp.core/doc/javadoc/index.html" />
     </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

    ------------------------------------------------------------------------
    _______________________________________________
    stp-dev mailing list
    stp-dev@xxxxxxxxxxx
    https://dev.eclipse.org/mailman/listinfo/stp-dev

------------------------------------------------------------------------

_______________________________________________
stp-dev mailing list
stp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/stp-dev

Back to the top