Use of topic descriptions

[Jim Campbell <jwcampbell gmail com>]

Hi All,

I wanted to suggest another change in the approach to user help.  Specifically, I wanted to suggest limiting the use of the topic descriptions.  

Here's what I'm thinking . . .  we have the topic title, which describes the help topic, and then we have the topic description, which provides additional detail on the topic.  In a lot of cases, the description and the topic title say basically the same thing.  In some other cases the title is very non-descript, and the description gives you the info as to what is actually included.

I think that we can do without the descriptions, and just make sure that the title adequately describes the topic.  I think this would have a number of benefits.  There's less for the user to read (making it easier to scan for topics that might be relevant to them), there's less for translators to translate, and each topic takes up less space on the screen / page, thus allowing us to add more topics without things getting too cluttered.

I don't think there's much downside to not including them, either. In a worst case scenario, a user clicks on a topic that isn't relevant to what they're looking for, and then they click on the back button to look for other topics.

In some cases, I think it is still ok to use the descriptions (particularly where something may be extra complex), or perhaps in some introductory sections, but overall . . . I think the user help would be better without them.  

If you want an example of what this looks like . . . you can check out the gedit help on gitorious: http://gitorious.org/gedit-docs/gedit-docs  (I'll be merging them in with gedit on gnome.org soon . . . ).

Thanks for your consideration,

Jim