[Neil D Matthews <Neil.Matthews@sonydnse.com>] Re: GDP Handbook

["David C. Mason" <dcm redhat com>]

Hi guys,

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.

---

• Subject: Re: GDP Handbook

Dear All,

Some comments / thoughts on the GDP handbook -- some of these apply to the GDP
handbook itself and what *could* be considered best practice for other GNOME
documentation, especially (complete) manuals, etc.

Pedantry and document versioning issues.
------------------------------------------------

o    I think that there should be a version number for each document --- so
that you can unambiguously identify a particular version. I've used embedded
CVS tags in previous (LaTeX) documents --- perhaps the GDP could specify the
necessary "magic" to automate this (assuming that all docs are kept in CVS).
Might have problems between an authors numbering and a combined/collaborative
numbering?
    [The gdp document should have a version number.]

o    I think that there should be a date for each document --- so that you can
identify how old a particular version is. I've used embedded CVS tags in
previous (LaTeX) documents --- perhaps the GDP could specify the necessary
"magic" to automate this (assuming that all docs are kept in CVS).
    [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.]

Licensing issues.
------------------------------------------------
One I hate to bring up, but doesn't seem to be mentioned anywhere.

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

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

Basics of documentation style.
------------------------------------------------
PLANNING

Consider the target audience.
    Is jargon appropriate? May be appropriate for technical documentation, but
not introductory guides.
    What age-level?
    "Professionalism"? May be more important for say, office-related
documentation.

    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?

STRUCTURE

Refer to the version of the software that the document describes.
[
It would be really nice if this was machine-parseable.

    The help browser could consider that if the document is 1.1 and the
software is 1.2, then a minor automatic message could be provided? E.g. the
software on the system may contain bug-fixes/minor additions that may not be
documented here.

    The help browser could consider that if the document is 1.1 and the
software is 2.0, then a major automatic message could be provided? E.g. the
software on the system may contain major changes/additions that may not be
documented here, please consult the GNOME web-site for updated documentation,
as available.
]

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.

GRAMM[E|A]R

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.

=========================================

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

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.

Yours, rapidly running out of lunch-break,

Neil Matthews.

---

-- 

          David Mason
        Red Hat AD Labs

        dcm@redhat.com