Re: GNOME Handbook of Writing Software Documentation rough draft

[Eric Baudais <baudais kkpsi org>]

On Mon, Jun 03, 2002 at 12:29:54PM -0400, Alexander Kirillov wrote:
> First: thanks for doing this job!
> 
> 
> Second, here are some comments - in no particular order:
> 
> 1. Is there really any need to include tempaltes as appendices? I'd
> expect that providing a link to templates on the web should be enough
> -after all, Web access is required for all doc writers.  Anyway, having
> the template in a separate file is so much  more convenient than doing
> cut-and-paste from HTML. 

I'm not sure about this.  There is a need to have the current templates 
available to download from both the web and CVS.  Having them in the Handbook 
gives people as easy way to reference them, but they might be more up to date 
being web based.  I just left this in because it was in the previous version.
I think I'll take them out, but I want to be sure an updated version of the 
templates is on the GDP website first.

> 2. We should add that all docs should be validated using xmllint --noout
> --valid. It is not enought that xlstproc or yelp  produces no errror
> messages: xsltproc is not a vlaidating parser. 

Yes, this is added to my TODO list and will be added.

> 3. Later we should add info on creating printed output. I can try to
> write it. 

This will be must later.  I think the best way to do this is with the 
toolchain DocBook->XML-FO->TeX->PS/PDF.  There are XSL stylesheets which 
translate the DocBook into XML-FO.  PassiveTeX should then take the FO and 
make a dvi using TeX which can be used to make PS or PDF.  I've had problems 
installing passiveTeX because it is not packaged on Debian.

> 4. Please add reference to Dave Pawson's DocBook FAQ: 
> http://www.dpawson.co.uk/docbook/

Done.

> 5. In section "Cross-referencing ....": add also how one links to man
> pages and info pages 

I'm not sure how to do this.

> 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. 
> -------- 
> I am not sure it is a good idea. IMHO, one should suggest to the
> developer/previous author  that the license be changed to FDL. We should
> keep the previous license only if the maintainer explicitly says that he
> wants it. 



> 7. In "Packaging": one should add that the file COPYING-DOCS should be
> packaged with the app (FDL requires that a copy of the license be
> included in the package). 

Done.

> 8. In "Installing and Using Docbook": do you assume that the reader
> already has a working GNOME 2 installation? If yes, then there is no
> need to install any further packages. If not, then he can not use Yelp. 
> 
>   I'd suggest writing this section as follows:
>    - If you have GNOME 2, use Yelp
>    - If you don't have GNOME 2, then install all the packages listed
> below and GDP stylesheets form CVS and  run 
> xlstproc /path/to/general-custoimization.xsl mysdoc.xml 
> then use any web browser to view the result. 

Yes, I need to reorganize that section.  GNOME 2 is looking like it will 
install the stylesheets and DTD locally.  This is because distributions have 
different levels of XML catalog support.  When I wrote that section it was 
probable that some documentation writer and possible users would have to 
install a XML catalog.

> 9. In the same section, "Installing and Using Docbook": you explain how
> one tests whether XML catalog is OK, but do not explain how to fix
> problems. It'd be a good place to mention DV's script
> "buildDocbookCatalog". 

DV's script will be mentioned.  I will also try to give some common problems 
about XML catalogss since I was doing that kinda of troubleshooting for people
using Garnome.

> 10. In "2.5. Application Bugs": AFAIK, bug-buddy is a separate package,
> not a part of gnome-applets 

Done.

> 11. One section that is missing is "Converting GNOME 1.x docs to GNOME
> 2", explaining the changes that need to be done and providing a link to
> a script someone (jfleck?) wrote for this purpose. 

I think he wrote a document describing the changes from GNOME 1.x docs to 
GNOME 2.  This is something I forgot about and it will be added along with 
how to write a OMF file and convert old OMF files.

> 12. IIRC, Style Guide suggests that articles ("a", "the") in titles be
> *not* capitalized:
> http://developer.gnome.org/documents/style-guide/technicaldetails.html#GNOME-GRAMMAR-USAGE

Done.

> 13. We should also mention that docs must include <indexterm> tags for
> Yelp indexing. This is new for GNOME 2. 

I will talk about this in multiple parts of the Handbook.

Thanks for all your comments.  You've uncovered some parts which will need 
some more work that I didn't realize.

Eric Baudais

> 
> 
> On Fri, 2002-05-31 at 21:51, Eric Baudais wrote: 
> > Guys-
> > 
> > The first draft of the newly revised for GNOME 2 edition of the GDP Handbook 
> > is completed.  It is in CVS at gnome-docu/gdp/gdp-handbook.xml.  Any comments, 
> > suggestions, and critiques are welcome.
> > 
> > There are two sections which I need a developer who knows the help API to 
> > write.  One involves the C code for adding help to applications and the 
> > other involves the C code for adding help to applets.  Anyone who has had 
> > experience in implementing the code is welcome to write those two sections.  
> > Contact me if you are interested so we aren't duplicating work.
> > 
> > There is no mention of Scrollkeeper and OMF files.  This was an omission by 
> > me and will be added for the second draft when I review the structure of the 
> > handbook.  If anyone has any other sections which aren't in the Handbook but 
> > need to be just email the list.
> > 
> > Eric Baudais
> > _______________________________________________
> > gnome-doc-list mailing list
> > gnome-doc-list gnome org
> > http://mail.gnome.org/mailman/listinfo/gnome-doc-list
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list