Re: Yelp Help documents

[Shaun McCance <shaunm gnome org>]

On Wed, 2006-01-11 at 23:44 -0700, Brent Smith wrote:
> I've written a manual for Yelp that uses gnome-doc-utils.
> Please let me know if it works for you and if you think
> certain sections need addressed or additional topics need
> added.

Hi Brent,

Thanks, we've needed some Yelp documentation for a while.
But I'm not sure it should really have its own manual.
Instead, we should probably just incorporate all of this
into the User Guide.

Some high-level comments, no writing style nitpicks:

User documentation should be written for people who have
no idea what DocBook is.  Clearly, you want to provide
all useful information for more savvy users, but it's a
matter of how you structure all that data.

We never use the word Yelp anywhere user-visible.  The
only exception is in About, and I'm not wholly happy
about that either.

Section 2.2 basically just reads the interface back.
I know all of our documentation is written like this,
but it's not very helpful.

'Usage' shouldn't follow the menu items.  Instead, it
should follow tasks.  So 'Print a Page' and 'Print a
Document' should just go under 'Printing'.  And then
there should be real prose explaining your printing
options.  Same thing for Back/Forward and the whole
Previous/Next/Contents thing.

Since 'Usage' is just following the menu items, it's
missing information on how to use Yelp.  Sure, you
use the menu items sometimes.  But usually you just
browse around.  A couple of paragraphs about how the
documentation is organized into documents, and how
they're all cross-linked, would be useful.  Proper
language usage can actually hype the whole thing,
while still just being instructional.

Those subsection titles are all imperatives.  The
general practice in technical writing is to use
some sort of noun, which is usually a verbal of
these things.  That leaves infinitives ("To Go
to Help Topics") and gerunds ("Going to Help
Topics").  Sun seems to love infinitive titles,
but I hate them.

If we're to have information on command line usage,
it should be complete.  So when we say you can use
file:// URIs, we should also say you can just use
absolute paths.  And relative paths.

ScrollKeeper and g-d-u probably aren't very relevant
here.  That sort of information would be useful in
the System Administrator's Guide, in a section about
the help system.

You know, I don't think any of our documents have
information on contributing.  I think it's a great
idea.  Great.  If we just incorporate this into the
User Guide, though, then there should probably be
one grand section on contributing, giving some info
on the various subprojects like the GDP.  And it
should then have some text about Gnome being free
software, and how you can contribute to make it
better, etc.

And probably other stuff.  Much thanks.

--
Shaun