Task Topics Prototemplate

[Shaun McCance <shaunm gnome org>]

One of the things Lynda suggested at Woscon is that tasks
should have an introductory paragraph that states exactly
what the reader will be able to do after reading the page.
This lets the user know immediately if this is the page
she wants to read.  It also reminds us what we're writing
about, so we don't wander around in our writing.

Lynda used the term SWBAT, "student will be able to", as
opposed to "know how to", because it provides a testable
objective.  And I think that's a terrific mindset for us
to have when looking at task objectives.  But I also think
it makes for a very dry introductory paragraph if we use
the task objective directly.

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!"

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.

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.  One thing that comes to mind is
text about common problems, with links to troubleshooting
pages.

Thoughts?

--
Shaun