Re: GDP Handbook

[Telsa Gwynne <hobbit aloss ukuu org uk>]

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.

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

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

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

> o    Each GNOME document should fall under a license TBD, referenced /
> included in the document itself.

TBD? To be determined, or..?

>     Is jargon appropriate? May be appropriate for technical documentation, 
> but not introductory guides.

Having tried to document an app (gtop) which involves some fairly
complicated ideas (RSS, Resident, and okay, I admit it, I find remembering
how memory, diskspace, CPU and swap interrelate a pain), I agree, but
there has to be a way to deal with it more neatly than I did: explaining
each concept as it became necessary. That approach requires someone to
read through in a linear fashion. I nearly threw in a glossary at
one stage, but on reflection I decided that if I did that, people who
needed it would be spending all their time flipping between the text
and the glossary and lose track of where they were.

>    Write for ease of comprehension.
>        Consider people using a second language --- keep sentences simple and
> brief.
>    Write for ease of translation.
>        Avoid "colorful" metaphors?
>        Don't use complex sentence forms?

I found the feedback from people who aren't native English speakers
really helpful on this. I would love some of the translator folk to
make a list of "things it's really hard to translate". I saw one
person looking for a word for 'killfile' (in pan) that didn't sound
so much like a death-list in his language :) That might be a bit
tricky to list in advance. I can think of things like "you can't 
translate puns" (well, I heard a joke in English and German that
had the same pun once, but that's the only one I've heard ever!) 
and "if a word has two meanings in English, make sure it's obvious 
which meaning is intended" but there must be things I'm missing.

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

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

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

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

Telsa