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