Re: [platform-doc-dev] Eclipse documentation styles

[Jeanette Deupree <deupree@xxxxxxxxxx>]

Mike (and any others willing), We welcome any updates to the Eclipse doc
HTML files. If you find typos or HTML coding problems that you can easily
fix, please do so and post a brief description of the changes/fixes to this
mailing list. Changes will then be reviewed and, if accepted, committed
into the open source doc projects. Any problems that you find but you can
not fix, please open a bug report in Bugzilla.

We would also like solicit any feedback or suggestions for improvement to
the content of the Eclipse 2.0 documentation. Please respond to this
mailing list with ideas.

Thanks, Jeanette

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

Jeanette Deupree
RTP NC
919-254-1149 (tieline 444-1149)
deupree@xxxxxxxxxx



                                                                           
             Mike Behm                                                     
             <mbehm@redhat.c                                               
             om>                                                        To 
             Sent by:                  platform-doc-dev@xxxxxxxxxxx        
             platform-doc-de                                            cc 
             v-admin@eclipse                                               
             .org                                                      bcc 
                                                                           
                                                                   Subject 
             01/12/2003                Re: [platform-doc-dev] Eclipse      
             06:41 PM                  documentation styles                
                                                                           
                                                                           
             Please respond                                                
                   to                                                      
             platform-doc-de                                               
                    v                                                      
                                                                           
                                                                           




Hi Susan,

I'm working on documentation for a port of Eclipse and a CDT to Linux.
Being outside of the core documentation development process, I don't
know about any progress on the post-mortem items. However, I can pass
along some observations gained from the experience of porting the
core documentation to Linux.

> We will improve the way we do documentation.

In looking over the core documentation I have come across typos and
HTML coding problems. If there is a place to send edits/review
comments, I'd be happy to do so.

> We will define a style guide

Excellent idea.

In my porting of the core documentation to Linux, I've chosen to extend
the use of style sheets. It turns out that a sizable number of Linux
users use Netscape Navigator 4.x. As a result, I've had to create two
CSS files:
 -one that holds styles that all browsers (even Nav 4) render well
 -one that modern browsers can render, but Nav 4 cannot
The latter styles I put into a file called notnav4.css, and I've had
to add this to all of my source files:
 <style type="text/css">
 @import url(../notnav4.css);
If you have the same problem, you might want to try that solution too.

> and agree on tools.

You might find that HomeSite5 and UltraEdit are very useful tools for
raw HTML.

> We will invest in tools that make the checking less painful.

HomeSite has a link checker, an "HTML Tidy" function, an HTML
validator, and a spelling checker. If you use a style guide that
calls for marking up text that appears on the Eclipse GUI with
something like <span class="guilabel">Project name</span>, HomeSite
has a "snippets" function that inserts the markup you define (the
<span class="guilabel"></span> part) with a key click. This can be
very useful. However, you should be aware that HomeSite is something
of a resource hog.

UltraEdit also has a spell checker and HTML Tidy, but I mainly use
it for global search & replace across a set of directories.

http://www.macromedia.com/software/homesite/
http://www.ultraedit.com/


Susan Franklin wrote:
>
> Mike - I was just reviewing the discussions from December.
> You were wondering about tags such as:
>
> Here are some of the tags and markup I've seen but have questions about:
>
>   <P CLASS="Para">
> (From the way it is used, I don't think that this differs from <p>.)
>
> Some history is that some of the original docs for eclipse were generated
> by Framemaker.  That is the origin of some of these tags.  They were
> stripped out of some docs and left in others, depending on who was doing
> the writing and what tool they moved to for authoring.
>
> I just saw this from the 2.0 post-mortem notes:
>
> We will improve the way we do documentation.
> We will define a style guide and agree on tools.
> We plan and test documentation as part of the development process.
> We will invest in tools that make the checking less painful.
> We will provide content earlier.
>
> Has anything happened on this front since 2.0?  I'm about to start making
> some changes to doc...
>
> susan
>
> _______________________________________________
> 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