Re: GNOME Handbook of Writing Software Documentation rough draft

[Alexander Kirillov <kirillov math sunysb edu>]

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. 



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. 

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

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

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

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

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. 

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

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

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. 

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
 

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


That's it for now.

Best,
Sasha


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