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