Re: GDP Handbook

[Neil D Matthews <Neil Matthews sonydnse com>]

Telsa Gwynne wrote:

> Oh, how I hate mutt's habit of not putting > marks into forwarded
> messages. I'm not clear on whether some of what's quoted below was
> all the person mailing Dave, or whether some are Dave's additions.

My fault, I should have posted directly :-)

> I snipped some of the "How to do it in LateX" just for brevity.

Snipping also active :-)

> > Here are some comments I got this morning from an interested party
> > that talk about our gdp docs - some decent comments we should take into
> > consideration.
> [munch]
> > o    I think that there should be a version number for each document
> > --- so that you can unambiguously identify a particular version.
> >
> >    [The gdp document should have a version number.]
>
> I agree. What about this be the revhistory stuff? I was playing with that
> on something else, and it can get long very easily. But it's there.

>
> > o    I think that there should be a date for each document --- so that you
> > can identify how old a particular version is.
> >
> >    [The gdp document should have a (fine-grained) date --- especially if
> > it's subject to (hopefully) rapid evolution. Basically, if the document
> > is >6 months older than the software then that gives an indication of its
> > relevance, etc., bug-fixes, outstanding items, etc.]
>
> Would "this document last updated (date)" do? We could also use this
> in the templates: "This document last updated (date) and about version
> (version) of the gnome-coffee-maker program" (Or whatever.)

This is exactly what I was looking for! To be honest this could also go in the
"Doctable" --- as a hint to which documents might bear some review / update.

> > o    I note the (c) statement, etc., but there is no statement as to the
> > licensing regime that the document is under (if any) --- e.g. public domain,
> > LDP, GPL, LGPL?
> >    [The gdp document and all other GNOME documents should have a clear
> > reference to its terms and conditions, etc., etc.]
>
> There seems to be an unspoken "GPL your doc" hint, largely because
> practically every example I've found is GPL'd. Question for the applet
> handbook: is the whole thing to go under one licence, or can people
> pick different licences for their different contributions? I'm happy
> with GPL personally, but people differ: I also like the Open Content
> one, and GNU are preparing a GNU documentation licence, too. GNOME
> is the GNU network whatever it is, so I assume that GNUy licences
> make sense :)

This is what I was hoping, but I was suggesting that it be part of the GDP process
--- I started looking at updating some documentation a while back and wanted to
"steal" some documentation to update another document, but couldn't identify the
licencing terms, etc.

> > o    Each GNOME document should fall under a license TBD, referenced /
> > included in the document itself.
>
> TBD? To be determined, or..?

Sorry, jargon / also failing my own acronyms should be expanded the first time
that they are used rule :-) TBD (to be determined).
Aside: This is important as I've been in meetings where people have tried to look
up ASAP (as soon as possible) in a dictionary.

[SNIP!]

> > It would be really nice if this was machine-parseable.
>
> Packaging problems? Particularly the applet doc. Presumably the
> applet doc will refer generally to the gnome-applets version number,
> but the applets themselves vary in their numbering schemes. I like
> the "This doc refers to foo-1.1 and the package is foo-1.2" idea, but
> what happens if the applet is version 0.9.7 and thus a lower number?

Hmmm, the "easy" way is to consider the package number, as the definitive
numbering when comparing document / applet version --- but I guess that this may
be too coarse.

> > Make sure the document is easily searchable.
> > Consider that it may not be read in-order (include cross-references).
> > Describe "easy" items first.
> > Most important to show how to undo an operation, or to cancel it.
> > Show how to run the command from a shell, as well as menu, etc. if possible.
>
> I agree with all of those. I'm currently playing with gnome-core-1.1.x
> which is a little different in menu layout to 1.0.5x, but I still think
> that in the options you get when you right-click on a menu entry, you
> should see "Command line to run this at shell prompt: <whatever it is>".
> But that's me, and it's not doc-related :)
>
> > Expand acronyms on the first occasion / cross-reference to a glossary.
> > Spellcheck
> >    ispell, et. al.
> > Ask for proofreaders.
> > Leave for a week and then re-read carefully.
>
> I think we have all these in the guidelines, no?

No, the section is empty at present.

> > One ongoing simple project might be to consider a simple GNOME glossary
> > document and have references to glossary entries jump directly to that
> > document (fragment) -- to get consistent definition, etc.
>
> I like this idea. How do you structure the glossary, though? Straight
> alphabetical, so that programs, concepts, terminology are intermingled,
> or broken down? On my list of "When I get time" is a list of all the
> screen, window, root window, workspace, desktop, pointer, mouse, cursor,
> things, because different window managers use different terms for what
> appear to me to be the same thing, and it was _so_ confusing at first!

I had some vague notion of document "fragments" that could be reused in a variety
of situations, e.g. reusing a fragment from the Orbit docs to introduce the
concept of CORBA / be part of the glossary / be part of Orbit docs --- any updates
would be reflected in both docs.

The GNOME FAQ has a "fragment" that describes the compilation process / required
packages --- these fragments might be better taken from the up to date GNOME
web-pages, c.f. Ocotber GNOME, et. al. --- again updates would be reflected in
both docs.

There might be generic fragments about the GNOME website(s), developing, GDP, CVS,
Tarballs, compilation, etc., etc.

> > Possibly also acronyms, etc.
> > GNOME PNG DTD XML HTML

> > Finally, missing tools (as I see it) are red-lining to show differences
> > between (on-line/printed) versions and "commentary" tools, like in Acrobat4.
> > Is it acceptable to post annotated PDF's, etc.
>
> I don't quite follow this bit.

Just a general wishful-thinking that reviewing different versions of documents is
much easier when you can read the changes, c.f. red-lining / changebars.

The Acrobat comment was simply that I find it easier to read printed (.ps / .pdf)
versions and annotate the issues on the page --- see an annotation that I did some
time ago of the GNOME FAQ --- you may need the free Acrobat v4 reader from Adobe
(http://www.adobe.com).

Cheers,

Neil.

gnome-faq.zip