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 _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
