Re: Yelp Help documents

[Brent Smith <gnome nextreality net>]

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

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

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

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

--
Brent Smith <gnome nextreality net>
IRC: smitten