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

[Kevin_McGuire@xxxxxxxxxx]

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: platform-doc-dev-admin@xxxxxxxxxxx 02/21/2003 12:20 PM Please respond to platform-doc-dev

To:        platform-doc-dev@xxxxxxxxxxx         cc:                 Subject:        Re: [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