GDP Handbook writeup/feedback.

I just managed to finish reading over the GDP handbook, and it looks pretty
good.  It doesn't seem to contain much information on using DocBook right
now, but I see places where that will be.  I've got plenty of comments, some
of them are rendering, some are content.  The page numbers that I'm
referring to are from the .ps version of the handbook, since that's the
easiest way to reference things.  

On page 2, the last sentence of the Goals section says "Most GNOME
applications have its own manual in addition to context sensitive help."
That should probably be "their" rather than "its".

On page 4, there is a note in the top half of the page which seems vague to
me.  Which users guide is it referring to here?
	There also seem to be two rendering problems on this page, one in
the paragraph on "Installing DocBook" and the other in "GDP DTD (PNG Image
Support).  Are these bugs in the tools that you're using?  There are a
number of other places where this turns up, but I'll not mention them here
because they look to me like problems with the tools.

On page 5, there are some notes about where catalog files will be stored.
I'm assuming that the RH note is where the catalog file should be according
to the FSSTND.  Perhaps it should be noted as "On systems which comply with
the FSSTND the catalog should be /here/; on systems which comply with the
FHS the catalog should be /there/

On page 10, in the second paragraph there is a parenthesized note about the
typical presentational markup being for an 8.5x11 piece of paper.
Personally, I think HTML is becoming widespread enough that a lot of
presentational markup is being done for web-pages.  Perhaps not a majority,
but it might be worth noting that HTML is presentational and not structural

On page 11 the screenshot didn't get included in the .ps format, perhaps
more tools problems?
	Down in the section about program listings, it says that all of the
examples used the "<programlisting" tag.  Maybe stick a > on the end of

On page 13 in the section on links and reference continued from page 12,
there's an example of a link to "GNOME web page".  Isn't it "The GNOME web
site"?  To me page is just one page, site is an array of pages.  Not sure
whether the "the" is necessary, depends on how you view GNOME, I guess.

General note that I thought of as I marked this up, a lot of the examples
have a "this code produces this output".  That's all well and good, but not
very general, and not the whole truth.  That code produces that output when
processed with these tools and these stylesheets.  Perhaps there should be a
section explaining that...

Well, that's enough tearing it apart for now I suppose, now for a request.
Could there be some sort of a formal "editors" group or something?  I think
that editing is very important to documentation, but nobody seems to take
the time to set up anything formal for the editors.  Thanks,

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]