Re: GNOME Handbook of Writing Software Documentation rough draft

[Eric Baudais <baudais kkpsi org>]

On Tue, Jun 11, 2002 at 09:13:01PM +0100, Irene Ryan wrote:
> 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?

Yes, this was an old leftover from GNOME 1.4.  Fixed.

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

Well, this is available in the Linux version of GNOME 2 in Actions->Take a 
Screen Shot.  There are other tools mentioned so I don't see this as a problem.

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

Yes, it is fixed.

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

I used the UG as an example instead.

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

I used a different title instead to show it can be done.  The templates have 
an example of a note with no title.

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

Fixed.

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

This is not a requirement of the GFDL.  However it is a good thing to indicate 
this in the revision history section otherwise future documenters might think 
the documentation hasn't been rewritten in a long time.

Maybe this shouldn't be in the GDP Documentation Conventions section.  Can you 
suggest a better place to put good things to do in a document which aren't 
actually required?

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

Fixed.

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

Fixed.

Thanks for your comments Irene.

Eric Baudais
> 
> 
> 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