Re: GNOME Handbook of Writing Software Documentation rough draft

[Pat Costello <Patrick Costello Sun COM>]

Hi Eric, 

Some comments on the GNOME Documentation Handbook (GDH): 

Templates
=========

Wherever possible we should refer out to gold sources, so as not to duplicate 
information, in other words we should not include templates in the GDH.  

Copyright Information
=====================

> > 6. in 5.2.3, "Copyright information":  
> > -------- 
> > If there is existing documentation then the author's copyright notice
> > and license must be used even if you do not use the existing
> > documentation. This is to ensure that licenses and copyrights stay
> > intact from version to version of the application and documentation. 
> > -------- 

This is not what the GFDL says. The GFDL refers to derivative works and modified 
versions. The GFDL does not require that copyright be given to previous authors 
of existing documentation, if you are not modifying their original work. Having 
said that, you would always have to make sure that the title of your 
documentation is sufficiently different from existing documentation to 
distinguish the two works. 

DocBook Basics
==============

In January 2002 I had a discussion with Sasha, John Fleck and Dan in the context 
of the GDSG, about moving the DocBook Style chapter from the GDSG to the GDH. 
The argument for this is as follows:  

The GDSG is essentially about the following: 

- information content
- information structure
- information design. 

Whereas the GDH is about the following: 

- the technical details of document development
- tag usage
- file management 

The two groups of information are distinct and all of the DocBook type 
information would be better suited to the implementation approach of the GDH. 

Packaging of Applets
====================

Why should the treatment of image files be any different for applets than for 
applications? Why should image files for the former go into the same directory 
as the applet.xml file? Why shouldn't the applets also have a /figures file? One 
of the reasons why the cvs/gnome tree is so confusing is because there are 
several different file management conventions going on at the same time. If we 
all agree to treat image files in the same way, no matter what the class of 
program, then it is one less file management convention to remember or confuse. 

Pat