Issue status update for http://drupal.org/node/26139 Project: Drupal Version: 4.6.2 Component: other Category: tasks Priority: normal Assigned to: Robin Monks Reported by: Robin Monks Updated by: killes@www.drop.org Status: patch I think it would be nice if the help texts could be split up in one t()ed string per paragraph. That way they are much more likely to be at least partially translated by translators. Also, you can then leave the paragraph tags out from the t()ed strings and have a bit less html in those. killes@www.drop.org Previous comments: ------------------------------------------------------------------------ July 1, 2005 - 02:02 : Robin Monks Attachment: http://drupal.org/files/issues/4-6-2-helptext.patch (126.02 KB) This patch adds help text to all core modules per the information at http://drupal.org/node/24768. This patch should be applied to 4.6.x and CVS HEAD. Robin +1: No broken links. Easy access to core module help is going to make Drupal much more accessible / lower the learning curve. Andrew ------------------------------------------------------------------------ July 1, 2005 - 07:40 : Dries Quick review: 1. We don't glue words together: %administerprofile should be %administer-profile, %administerwatchdogevents should be %administer-watchdog-events, etc. 2. We try not to abbreviate words: %stats should be %statistics. 3. We don't use spaces in a href-tags! Wrong: <a href = "%foo" title = "my foo">Good: <a href="%foo" title="my foo"%gt; 4. Why has this line been added: error_reporting(E_ERROR | E_PARSE);? 5. You can't write "administer >> menus >> add menu" without escaping the >>'s. In results in invalid XHTML. 6. Writing "administer >> menus >> add menu" is dangerous because these paths are dynamic (eg. they can be changed using the menu module). I guess it is uncommon though. 7. You changed settings.php. 8. We should avoid using the word "node" in user-level documentation. We try to use "post" or "content". 9. Some title-attributes of the a href-tag start with a capital letter, some with a small letter. Most title-attribute are useless; they don't add any value. In fact, they are often less descriptive than the content enclosed in the a href-tag. At least *90%* of all title-attributes can be *removed*! Examples: <a href = "cron.php" title = "cron page">cron page</a> (redundant title) <a href = "%adminsettings" title = "">administer >> settings</a> (empty title) <a href = "%addavocabulary" title = "add a vocabulary">administer >> taxonomy >> add vocabulary</a> (useless title) <a href = "%administertaxonomy" title = "administer taxonomy">administer >> taxonomy</a> (useless title) ------------------------------------------------------------------------ July 1, 2005 - 07:45 : Dries Also, the patch only applies partially against HEAD. 6 modules don't get updated. ------------------------------------------------------------------------ July 1, 2005 - 08:34 : Amazon Quick review: 1. We don't glue words together: %administerprofile should be %administer-profile, %administerwatchdogevents should be %administer-watchdog-events, etc. Ok, we can change that. 2. We try not to abbreviate words: %stats should be %statistics. Ok, I'll change the Drupal handbook source for this. 3. We don't use spaces in a href-tags! Wrong: Good:
menus >> add menu" without escaping the >>'s. In results in invalid XHTML.
Ok, we will escape the 's. That is a mistake. 6. Writing "administer >> menus >> add menu" is dangerous because these paths are dynamic (eg. they can be changed using the menu module). I guess it is uncommon though. Admin help is for the new users who are most likely to be using the navigation menu. The barrier of adapting new user documentation is too high for a fully dynamic system. Could you suggest some phrasing that acceptable? In the navigation menu: administer >> menus >> add menu. But even that is subject to change. Please advise. 7. You changed settings.php. We will fix that. 8. We should avoid using the word "node" in user-level documentation. We try to use "post" or "content". Ok, we will remove the word node and use post instead. 9. Some title-attributes of the a href-tag start with a capital letter, some with a small letter. Most title-attribute are useless; they don't add any value. In fact, they are often less descriptive than the content enclosed in the a href-tag. At least 90% of all title-attributes can be removed! We were told to add titles for accessibility reasons. If this is not the case we can remove them. Examples: cron page (redundant title) redundant, but harmful? administer >> settings (empty title) Ok, we will find all the empty titles and either remove them or populate them with appropriate titles. administer >> taxonomy >> add vocabulary (useless title) The user base is changing. Simple english phrases are more meaningful to new users. I believe it's a mistake to overlook what is simple to the advanced user, but valuable to the new user. administer >> taxonomy (useless title) Again, a simple phrase while seemingly redundant to advanced users who are not intimidated by symbols such as >> can be helpful to new users, and those who rely on titles for accessibility. The hope was that themes that supported mouse over text would benefit over time as the documentation improved. However, it's a minor point and we can strip it away all the titles if it doesn't conform to Drupal guidelines and standards. I'd prefer to allow the documentation to evolve with more descriptive titles over time as documentation contributions increase. We will aim to have a new patch meeting the points highlighted above in approximately the next 12 hours. We will also apply the same standards to the 30 contributed modules. Thanks for the quick evaluation. It's greatly appreciated. Cheers, Kieran ------------------------------------------------------------------------ July 1, 2005 - 15:32 : Goba Forum.module, locale.module, drupal.module etc. patches include some HTML errors, starting a new paragraph, then immediately starting another one. It might be a good idea to validate the HTML sources of the helps so random fixes in the future will not give more job to the translators. You can do this with extracting the po files, and examinging the files extracted. It is possible that given a standard HTML enclosure (html, head, body) the pot files will validate as XHTML, I never actually tried large scale help text validation. There are also other HTML validity problems in the search module patch (unclosed list item tag). There might be others elsewhere. It might also be a good idea to automatically spell check the strings (as it was done with the dev comments before), so that it is less likely that these need modification later. Keep in mind that translating all this stuff takes quite a bit of time (this is why these are not translated in some cases), so it would be good to do the best for the first time (which is your intention anyway :).