Re: Task Topics Prototemplate

[Shaun McCance <shaunm gnome org>]

On Mon, 2009-08-24 at 11:20 +0100, Phil Bull wrote:
> Hi guys,
> 
> On Sun, 2009-08-23 at 09:09 +0200, Milo Casagrande wrote:
> > I like the idea, and I was thinking of adding some sort of
> > introduction to some topics for Empathy, but I "feared" doing it: it
> > reminded me of the old docbook-way "in this section". Some topics
> > indeed need a short introductory paragraph, but I really like to see
> > them short and direct (and it's not easy sometimes to come out with a
> > short, clear and almost complete description of what you will be
> > talking). I wouldn't say that this will be a needed part for all the
> > pages though.
> 
> I think that in many (but not all) cases, an introduction will be
> redundant. The information contained in the introduction will often be
> contained in the title and description of the page.
> 
> If the list of aims of the topic is too long to reasonably fit into the
> <desc> tags, then the topic itself is probably too long or diverse, and
> should be split up.

The desc isn't displayed on the page though.  You don't want
to expect users to click back to reread the desc to verify
they're on the right page.  And they might have gotten there
from a Help button or such, where they never see the desc.

I do take your point about redundancy.  But I don't think
all redundancy is necessarily bad.  It's common practice in
writing for the first paragraph to effectively restate the
title.

Here are reasons I think it's useful:

1) Titles have to be relatively short, and can't always use
all the terms users know.  We can restate things with a bit
more verbiage.

2) I tend to think that most tasks could stand to have a link
to a concept page.  I'm certain the IRC page I used as an
example should.

3) If you stop and think about what a user is *really* trying
to do, you'll often find that this task is only part of it.
Sometimes we have to break up tasks.  But this gives us the
chance to direct users to the rest of what they need.

In the "Create an IRC account" example, I don't think any
users are really trying to create an IRC account.  They're
trying to get onto irc.gnome.org#docs for our Q&A session.

  You can use Empathy to connect to one or more IRC networks.
  To connect to an IRC network, you have to create an IRC
  account in Empathy.  You need to create an account before
  you can join an IRC chat room or chat with a user on IRC.
  To see how to chat on IRC, see <irc-manage>.

If we had an IRC concept page, we could just link to it from
the first occurrence of the word IRC, obviating the need for
even more text.

(By the way, wouldn't it make sense to link "Create an IRC
account" into the "Use IRC" guide?  It doesn't mean we have
to remove it from "Manage accounts".  That's the beauty of
Mallard.)

> > The other day I was thinking about using the description of a topic
> > (<desc></desc>) as a subtitle for the topic title, something to see
> > not only in the guide page, but also in the topic page itself.
> > Something like this:
> > 
> > <b>Title of the topic</b>
> > --------------------------------------------------
> > <small><i>Description</i></small>
> > 
> > So that we have a really small description of the topic. But it could
> > end up cluttering the page...
> 
> I think that this is a really good idea. The description could be given
> less visual weight to prevent it from distracting from the page
> information, or cluttering (as Milo suggested).
> 
> We should also give guidelines on what should be contained in a
> description. If the aim of the description is to state what the user
> will be able to do after reading the page, then we don't need an
> introductory paragraph as Lynda recommended.

So I was just thinking that maybe we could allow desc as lead
content for page and section elements, to accomplish this sort
of thing.  It's already used in a block context on some formal
block elements.

I think this would also address what you raised in the meeting
yesterday about putting error messages at the top of the page
for troubleshooting topics.

> > > One thing that comes to mind is
> > > text about common problems, with links to troubleshooting
> > > pages.
> > 
> > We should try to find some common sentences to use, or at least a
> > common sentence start for different kind of problems, and topics also.
> 
> I don't think that we should use a common sentence start for different
> problems or topics, because they make it more difficult to differentiate
> between topics. Remember we tried the common "How can I..." beginning to
> Empathy topics? It made everything look the same, which impacted how
> quickly you could find the relevant topic.
> 
> Users are skimming for particular words or phrases when looking for a
> relevant topic. Common sentence starts are just noise that will get in
> the way. We should put the most important word first, if at all
> possible.

You're right.  I think I was just trying to prevent people
from writing this stuff poorly.  But this is obviously the
wrong way to do it.  Writers just have to learn to write
well.

--
Shaun