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

[Mike Behm <mbehm@xxxxxxxxxx>]

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