Re: GNOME Handbook of Writing Software Documentation rough draft

[Irene Ryan <irene ryan Sun COM>]

Hi Eric,

I just reviewed your draft of the GDP Handbook. Here are some comments:

Section: Getting Started Writing GNOME Documentation / Installing and Using DocBook / Images in DocBook
-- You mention that you should never include the extension of the image file but I found that my PNG images would not display unless I included the extension. I think this is mentioned elsewhere in the document also. Was this a previous requirement maybe?

Section: Getting Started Writing GNOME Documentation / GDP Document Templates / Screenshot Tools 
-- You mention Screen Shooter but this is no longer available in GNOME 2.0 or at least I think it isn't anyway. Also, if you are including the chapter about Procedures for Taking Screenshots, this section may not be necessary anymore.

Section: Getting Started Writing GNOME Documentation /GDP Document Templates / Screenshot Files 
-- I think someone else had the same comment but why do we need to keep figure files in the same directory for applets and in a figures subdirectory for applications? It doesn't make sense to have a different file structure for applets and applications unless there is a technical reason for this that I'm unaware of.

Section: The GNOME Documentation System / The GNOME Help Browser 
-- Third paragraph, last sentence, should remove the "such as the manuals for applets" part of the sentence since applet files are now single documents.

Section: DocBook Basics / Structure Elements / Notes, Warnings, and Tips 
-- You don't need to include the <title> tag unless you want to use a title other than Note, Warning, or Tip for the element so I think you should leave the <title> tag out of the example. The stylesheets display the appropriate title depending on the type of tag.

Section: DocBook Basics / Inline Elements / GUI elements 
-- This section suggests using the <guibutton> tag for checkbuttons (check boxes?) and radio buttons. I've only been using <guibutton> to mark up the labels on buttons that you physically click on to perform an action, that is the buttons that are defined in the GDSG at http://developer.gnome.org/documents/style-guide/gnome-glossary-button-types.html. I use <guilabel> to mark up check boxes and radio buttons. The DocBook TDG describes guibutton as "GUIButton identifies the text that appears on a
button in a graphical user interface". It describes guilabel as "GUILabel identifies text that appears as a label in a graphical user interface." 

Section: GDP Documentation Conventions / Conventions for All GDP Documentation / Revision History 
-- Second paragraph, second sentence, why do you need to indicate if a document was rewritten from scratch? As far as I know, this is not a requirement of the GFDL.

Section: GDP Documentation Conventions / Conventions for Application Documentation / Application Version Identification 
-- The application version is now specified in the <releaseinfo> tag within the <articleinfo> in the new templates. The code example given here needs to change.

Section: Writing Application and Applet Manuals 
-- Last paragraph, the entry on the Help menu is now called Contents instead of Manual.

Regards,
-Irene


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