Re: Yelp Help documents

Shaun McCance wrote:
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

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.

Respectively disagree.  I know your goal here is to make
the help browser transparent, but the fact is that it
provides significant functionality outside of just a
window that pop ups when users click help.  If this was
not the case, then why does it have a table of contents?

Fact is, people know it by the name "Yelp" because it's
cvs module is named that way, bugzilla lists it that way,
and half of the source code starts with "yelp_".

Sure yelp is supposed to be easy to use and transparent
to the user.  But if they decide that they want to start
developing docs for GDP and want to know the details about
how yelp works, I think there should still be a manual available.

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.

I agree that we should not assume the user knows what DocBook is.
But how else do you describe a feature that is directly related to
whether or not the underlying document is in DocBook format?

I don't think providing this as "extra information" hurts anything.
Perhaps a reference to what DocBook is would make sense.

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

Not true. see my above comment.

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.

I know.  Some of the content in my patch sucks, I agree.
But hey, it's better than nothing.

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

I thought about this while I was writing it.  It can surely
be shuffled around pretty easily.

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.

Point taken, I could include information about how documents
are cross-linke, etc.

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.

I wasn't entirely sure about how this works myself, and I
even looked at the source code.  It'd be nice if it was
documented somewhere so the developers could understand
how their own code works.

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.

I am trying to cater to people who want to understand how
yelp's architecture is structured.  Man pages are useful
because they are detailed.  Why can our documents also be

I find that a lot of our documents are crappy because they
provide no real information about how the program _really_

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.

Sure the bulk of this could be put elsewhere, but what's
wrong with linking to that information?  (Besides
the difficulty of maintaining those links over time)

And probably other stuff.  Much thanks.


Brent Smith <gnome nextreality net>
IRC: smitten

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