Re: GNOME Handbook of Writing Software Documentation rough draft

[Eric Baudais <baudais kkpsi org>]

On Tue, Jun 04, 2002 at 02:16:44PM +0100, Pat Costello wrote:
> 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.  

I'll take them out when the new GNOME 2 templates are put on the web.

> 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. 

I will remove the phrase "even if you do not use the existing documentation."

When I wrote this section I wanted it to be generic as possible due to the 
fact that we shouldn't require the GFDL for documentation for all of GNOME.  
Using the GFDL is vastly encouraged and we won't expect anything else for 
core documentation, but there are third party applications which might not 
use the GFDL.  The GDH is read by, not only core GNOME documentation writers, 
but also by writers and maintainers of third party GNOME applications.

> 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.