Re: Task Topics Prototemplate

[Milo Casagrande <milo casagrande name>]

2009/8/23 Shaun McCance <shaunm gnome org>:
>
> I'm proposing that we start each task with an introductory
> paragraph that clearly states the task objective, but that
> we rephrase it for the user in the "You can" style.  Here's
> an example:
>
> Task objective:
>  After reading this page, the user will be able to create
>  a new account to connect to an IRC network.
>
> Introductory paragraph:
>  You can create an account to connect to an IRC network.
>
> It addresses the reader directly, and it has a sort of
> empowering feel to it.  And then we can link the words
> "You can" to a video of all of us saying "You can do it!"

Easter eggs... I love that! :)

> Right, sorry, scratch that last part.
>
> The introductory paragraph will then continue with an
> optional conceptual statement that links to a page with
> information you might need.  And then, if necessary,
> a quick explanation of what this task does *NOT* deal
> with, with links to where you can find that information.
>
>  You can create an account to connect to an IRC network.
>  IRC is a [ten word explanation].  Read more about IRC
>  on [IRC overview page].  This page does not deal with
>  how to [something else].  For information on [something
>  else], see [some other page].
>
> This can be split into multiple paragraphs, with the caveat
> that we should always try to ensure that the start of the
> steps list is visible without scrolling.

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.

> That still leaves what we write after the steps list.  For
> a lot of tasks, it will just end with the steps list.  But
> we should start thinking about best practices for how to
> write other information.

Yes, a best practice, but on a case-by-case basis: some topics might
need a little bit more than an introduction, some others just a simple
one, some others might end being not step-instructions but just
descriptions.

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

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

-- 
Milo Casagrande <milo casagrande name>