Re: Task Topics Prototemplate

[Phil Bull <philbull gmail com>]

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

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

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/people/philbull