Re: adopting the Style Guide

[Eric Baudais <baudais okstate edu>]

On Mon, Oct 15, 2001 at 08:58:43AM -0400, Alexander Kirillov wrote:
> Yes, it is about time we make oficial guidelines for 2.0 docs. Style
> guide should be the first of them.

I feel that the Style Guide doesn't go into enough detail about what voice 
well formed documentation should be written in.  Currently there are some 
writers who are changing to docs from 2nd person to 3rd person, most notably 
the GIMP User's Manual.  Yet, still a lot of the docs currently written are 
in 2nd person.  Could someone either add a section to the Style Guide about 
the voice documentation should be written in or expand on an existing section?

> Additionally, it is about time we make
> decisions: 
>  - to switch to DocBook 4

Yes, definitely.

>  - probably update templates 
>  - announce the official scheme for cross-referencing (ghelp?
>  gnome-hep? help?) 

I would like to see someone update the entire GDP Handbook and also add:

1) How to include Scrollkeeper support for documentation and also how to 
create the OMF file and what to include in it.

2) Utilizing the Word List.

3) Explanation of glossary support.

4) How to utilize context sensitive help.

>  - index and keywords: will Nautilus or whatever new help browser we
>  use be able to create document index from index tags? if so, should
>  we start using  them?
> 
> But Style guide should definitely be officially adopted ASAP.
>
> Best,
> Sasha

I agree too.

Eric Baudais