Home » Eclipse Projects » Platform - User Assistance (UA) » Re: General user documentation question
| Re: General user documentation question [message #472305] |
Thu, 07 February 2008 15:03  |
Eclipse User |
|
|
|
Originally posted by: nospam_kowalskilee.gmail.com
Hi Pete,
I'm not part of the Eclipse development team. I will respond with some
things that I am aware of as someone who's attended EclipseCon and
conversations with committers working on various Eclipse projects.
I think the answer you'll get from Eclipse committers is "It depends".
The reason is because the answer depends on what you picture is the
"Eclipse development group". It is not one monolithic team. Eclipse as a
whole consists of many different projects, and each project can choose
their methods to generate and manage the user documentation associated
with their project.
In addition, if by "Eclipse", you mean the Eclipse Platform project, or
the Eclipse Software Developers Kit (SDK) specifically, that too is
componentized, meaning it is made up of different software components
that are built by different teams. For example, the team working on the
PDE could choose to always use PDE itself to create the documentation
files necessary for the PDE help, while the JDT team could choose a
different method if they want.
Eclipse itself was architected to be flexible. That flexibility allows
developers who commit code to use whatever mechanism they find best to
generate and manage the user documentation--as long as the content files
that get deployed into the system match the formats (e.g., DTDs) that
the underlying system expects.
At a project level, I believe the Data Tools Project is sourcing their
user documentation files in DITA XML, and then transforming that output
using the DITA Open Toolkit to create the resulting content files that
get deployed into the Data Tools Project components. I think that in the
past, the Web Tools Project also used DITA XML. Other projects might use
other tools to generate the file formats required by the Eclipse user
assistance infrastructure.
Hope this helps--if only to generate some follow-up discussion,
Lee Anne
Pete Ellis wrote:
> Hello all,
>
> I suppose I'm cross-posting this question from the eclipse.platform.ui
> newsgroup, but my curiosity is getting the best of me. Can anyone in the
> Eclipse development group chime in on what mechanism is used to generate and
> manage the user documentation HTML that is displayed via the Help framework?
> Is there a specific web publishing package or HTML authoring tool that the
> Eclipse team uses?
>
> I'm in the position of having to write user documentation for my company's
> Eclipse-based tool sets, and am looking to adopt an approach that is known
> to work well.
>
> Thanks for any thoughts on this,
> -Pete
>
>
|
|
| |
| Re: General user documentation question [message #472313 is a reply to message #472312] |
Tue, 12 February 2008 10:43  |
| Eclipse User |
|
|
|
Originally posted by: nospam_kowalskilee.gmail.com
Hi Pete,
As far as I know, there are multiple companies that contribute to DTP,
and so some of them might not use the same editor as others.
To get a more accurate response from people working in DTP, there is an
eclipse.dtp newsgroup. You could post your question there about what
tools are being used by contributors to DTP to author their DITA XML for
the documentation. There's also a DTP web page and a mailing list, where
you could follow up:
http://www.eclipse.org/projects/project_summary.php?projecti d=datatools
The DTP 1.5 Documentation Guidelines are in the DTP area of the Eclipse
wiki: http://wiki.eclipse.org/DTP_1.5_Documentation
DTP main Wiki page: http://wiki.eclipse.org/Data_Tools_Platform_Project
I believe that one of the companies contributing to DTP uses the XMetal
editor, and has their Eclipse workbench configured with DITA XML files
in Eclipse projects, and when opening a file, calls their installed
XMetal Editor to open the file.
Myself, I have been trying out the Oxygen editor, which is available as
an Eclipse plugin, and therefore you can author directly inside your
Eclipse workbench. I'm not sure if XMetal has an Eclipse-based offering
as well.
Both Oxygen and XMetal are more friendly than trying to author the XML
directly in a flat text editor. Both are not free. Oxygen is priced
lower than XMetal, at least it was the last time I looked at their web
sites. The DITA OT User's Guide mentions using XML Buddy, which is a
available on the Eclipse Plugins page at eclipse.org. XML Buddy would be
an Eclipse-based authoring solution a la Oxygen. I'm not sure how much
XML Buddy provides in terms of WYSIWYG-ness.
Your "picture of success" to develop the documentation in the same
environment as the code is completely doable. You can definitely
configure your Eclipse workbench to run the DITA Open Toolkit
transformations that transform the DITA XML files into the resulting
help files (Eclipse help and also other formats like PDF if you need
them). That's why having the Oxygen editor as an Eclipse plug-in gets to
that picture of success: author DITA XML files inside a view in the
Eclipse workbench and then transform them directly in the workbench
also--developing the documentation within the same environment as the
code. :-)
Hope this helps,
Lee Anne
Pete Ellis wrote:
> Lee Anne - A quick follow-up: Do you know what specific tool is used by the
> Data Tools Project to actually author their DITA XML? Is it an XML editor
> of some sort, or perhaps a more friendly (read "WYSIWYG") word processing
> capability that is capable of exporting to DITA compliant outputs? My
> initial searches for documentation tools that support user-friendly
> construction of DITA compliant content turned up commercial products only...
> we're hoping to get our hands on an open source solution (or, better still,
> and Eclipse based solution... how nice it would be to develop our software
> and its related documentation within the same environment!!).
>
> Thanks, -Pete
>
>
|
|
| | |
| Re: General user documentation question [message #609889 is a reply to message #472312] |
Tue, 12 February 2008 10:43 |
| Eclipse User |
|
|
|
Originally posted by: nospam_kowalskilee.gmail.com
Hi Pete,
As far as I know, there are multiple companies that contribute to DTP,
and so some of them might not use the same editor as others.
To get a more accurate response from people working in DTP, there is an
eclipse.dtp newsgroup. You could post your question there about what
tools are being used by contributors to DTP to author their DITA XML for
the documentation. There's also a DTP web page and a mailing list, where
you could follow up:
http://www.eclipse.org/projects/project_summary.php?projecti d=datatools
The DTP 1.5 Documentation Guidelines are in the DTP area of the Eclipse
wiki: http://wiki.eclipse.org/DTP_1.5_Documentation
DTP main Wiki page: http://wiki.eclipse.org/Data_Tools_Platform_Project
I believe that one of the companies contributing to DTP uses the XMetal
editor, and has their Eclipse workbench configured with DITA XML files
in Eclipse projects, and when opening a file, calls their installed
XMetal Editor to open the file.
Myself, I have been trying out the Oxygen editor, which is available as
an Eclipse plugin, and therefore you can author directly inside your
Eclipse workbench. I'm not sure if XMetal has an Eclipse-based offering
as well.
Both Oxygen and XMetal are more friendly than trying to author the XML
directly in a flat text editor. Both are not free. Oxygen is priced
lower than XMetal, at least it was the last time I looked at their web
sites. The DITA OT User's Guide mentions using XML Buddy, which is a
available on the Eclipse Plugins page at eclipse.org. XML Buddy would be
an Eclipse-based authoring solution a la Oxygen. I'm not sure how much
XML Buddy provides in terms of WYSIWYG-ness.
Your "picture of success" to develop the documentation in the same
environment as the code is completely doable. You can definitely
configure your Eclipse workbench to run the DITA Open Toolkit
transformations that transform the DITA XML files into the resulting
help files (Eclipse help and also other formats like PDF if you need
them). That's why having the Oxygen editor as an Eclipse plug-in gets to
that picture of success: author DITA XML files inside a view in the
Eclipse workbench and then transform them directly in the workbench
also--developing the documentation within the same environment as the
code. :-)
Hope this helps,
Lee Anne
Pete Ellis wrote:
> Lee Anne - A quick follow-up: Do you know what specific tool is used by the
> Data Tools Project to actually author their DITA XML? Is it an XML editor
> of some sort, or perhaps a more friendly (read "WYSIWYG") word processing
> capability that is capable of exporting to DITA compliant outputs? My
> initial searches for documentation tools that support user-friendly
> construction of DITA compliant content turned up commercial products only...
> we're hoping to get our hands on an open source solution (or, better still,
> and Eclipse based solution... how nice it would be to develop our software
> and its related documentation within the same environment!!).
>
> Thanks, -Pete
>
>
|
|
| |
Goto Forum:
Current Time: Sat May 24 14:44:40 EDT 2025
Powered by FUDForum. Page generated in 0.04510 seconds |
Home