Re: [platform-doc-dev] docbook for eclipse documentation?

[Mike Behm <mbehm@xxxxxxxxxx>]

Hi Kevin,

I don't know if there is a _requirement_ to produce the documentation
in other formats, but it might be useful to have a PDF version of 
the tutorials so that users could print those pages and work through 
the steps without giving up screen space to the online help. 

If the tutorials were written in XML, SGML, or even FrameMaker 
(or a related product), it would be possible to provide both the HTML 
and a PDF. On the other hand, I don't think that there is any 
particular need for a printed version of all the other types of Eclipse 
documentation.

Of course, if you were to start to create some of the documentation
in a XML or SGML, as Scott points out, you do limit the potential
authors 
to people who are comfortable writing in those formats.


Mike


Kevin_McGuire@xxxxxxxxxx wrote:
> 
> Good comments Mike.  The doc suffers from being done in a rush at the
> end of the product cycle.  The discrepencies are because people didn't
> know the right way to do it (or were given incorrect advice).  It
> needs a style guide, a good review, more mapower, and an owner who
> oversee's its quality and provides advice which results in
> consistency.  A more rigorous structure generally increases the cost
> of authoring.  By increasing the cost of authoring we reduce the
> number of doc submissions.  I would rather see manpower go into
> increasing the quality of the content, with stylistic issues corrected
> as we come across them.
> 
> I admit though that I don't understand the requirements of publishing
> the doc in other formats and the technical issues this might raise.
> 
> Kevin
> 
>  Mike Behm <mbehm@xxxxxxxxxx>
>  Sent by:                                     To:
>  platform-doc-dev-admin@xxxxxxxxxxx    platform-doc-dev@xxxxxxxxxxx
>                                               cc:
>  02/21/2003 12:20 PM                          Subject:        Re:
>  Please respond to platform-doc-dev   [platform-doc-dev] docbook for
>                                       eclipse documentation?
> 
> Hi Scott,
> 
> I do use DocBook SGML when I'm writing manuals for printing/PDF/HTML.
> However, I don't know that SGML would solve the problems I see in the
> Eclipse online help.
> 
> SGML would force a rigorous structure on the online help, but
> generally
> I think that the current degree of structure is adequate. What is more
> problematic are the contents of some pages and the quality of the
> HTML.
> For example, do a search for "Select All" and look at the top three
> hits.
> 
> The biggest problem is that the information is not particularly
> helpful.
> It was written for completeness (the "we've documented all the other
> commands so we have to document these" approach), rather than in
> response
> to the question, "Why would anyone ever ask for help on 'Select All'?"
> (Possible answers: accessibility--what are the key strokes to select
> all?
> How do I move the focus to that window using only the keyboard? Is
> there
> a way to "Select 'Most'"? What operations can I perform with the
> selected
> text/breakpoints/expressions?) XML will not make the content better.
> 
> The next problem is that the HTML differs between the three pages:
> there
> is no highlighting on 'Console view' but there is on 'Expressions
> view'
> and 'Breakpoints view'. XML would not force the three terms to be
> marked
> up the same way (although it would certainly permit it). And XML would
> not apply the highlighting only to the words 'Console', 'Breakpoints',
> and
> 'Expressions', which is the convention used elsewhere in the
> documentation.
> 
> The problem that you can't see is that in other areas of the
> documentation
> the 'Select All' help would be part of a table or definition list as
> part
> of a description of a larger entity (such as the Console view). Again,
> XML would not prevent this--but a well-defined style guide would.
> 
> XML is certainly a useful tool--and thanks very much for providing
> those
> links! But even the adoption of XML would not take away for the need
> for
> a good style guide.
> 
> Mike
> 
> "scott.hasse" wrote:
> >
> > All,
> >
> > I am new to this list, but was following the Eclipse documentation
> styles thread.  It seems to me that a good approach to solving that
> sort of problem is to use an xml-based semantic markup language such
> as docbook xml for the documentation.
> >
> > Some of the benefits of this approach are:
> >
> > * The ability to change the structure, look and feel of the
> documentation easily.  Of course, many look and feel aspects of this
> can also be accomplished with style sheets, but having a semantic
> representation of the documentation gives you much more flexibility.
> >
> > * The ability to easily generate other formats of the documentation,
> such as a PDF book, via tools like apache's FOP.
> >
> > * The ability to automatically generate the plugin toc files.
> >
> > The obvious downside is that people would need to learn to create
> the documention in, for instance, docbook xml.
> >
> > I am currently working on translating some docbook-based project and
> organization specific documentation in docbook into the eclipse help
> plugin format, and it is working quite well.  I have created an xslt
> file that creates an eclipse help toc file from a docbook document,
> using the sourceforge docbook xml->xhtml chunking xsl transforms as an
> intermediate format.
> >
> > I am curious what you all think of this approach.
> >
> > Some useful links are:
> >
> > http://www.docbook.org
> > http://www.sourceforge.net/projects/docbook
> > http://xml.apache.org/fop/
> >
> > Sincerely,
> >
> > Scott Hasse
> > _______________________________________________
> > platform-doc-dev mailing list
> > platform-doc-dev@xxxxxxxxxxx
> > http://dev.eclipse.org/mailman/listinfo/platform-doc-dev
> _______________________________________________
> platform-doc-dev mailing list
> platform-doc-dev@xxxxxxxxxxx
> http://dev.eclipse.org/mailman/listinfo/platform-doc-dev