[drupal-docs] Fwd: [drupal-devel] [task] Admin help in core modules
Kieran Lal
kieran at civicspacelabs.org
Fri Sep 16 23:12:13 UTC 2005
Please review the admin help patch. It needs to be updated to the
latest admin help for Drupal after all the comments are removed and
documentation updated to address those comments.
Kieran
Begin forwarded message:
> From: Robin Monks <drupal-devel at drupal.org>
> Date: September 15, 2005 11:32:29 AM PDT
> To: drupal-devel at drupal.org
> Subject: [drupal-devel] [task] Admin help in core modules
> Reply-To: drupal-devel at drupal.org
>
>
> Issue status update for http://drupal.org/node/26139
> Post a follow up: http://drupal.org/project/comments/add/26139
>
> Project: Drupal
> -Version: cvs
> +Version: cvs
> Component: other
> Category: tasks
> Priority: normal
> Assigned to: Robin Monks
> Reported by: Robin Monks
> Updated by: Robin Monks
> Status: patch (code needs review)
> Attachment: http://drupal.org/files/issues/
> drupal.-.admin.-.help.patch (131.1 KB)
>
> New patch, hopefuly for 4.7.
>
>
> Comments, raves and rants welcome!
>
>
> Robin
>
>
>
>
> Robin Monks
>
>
>
> Previous comments:
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 00:02:17 +0000 : 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
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 05:40:04 +0000 : 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)
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 05:45:07 +0000 : Dries
>
> Also, the patch only applies partially against HEAD. 6 modules don't
> get updated.
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 06:34:05 +0000 : 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
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 13:32:38 +0000 : 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 :).
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 13:38:43 +0000 : killes at www.drop.org
>
> 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.
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 13:50:53 +0000 : Goba
>
> As a practicioning translator, and as the one who translated most
> of the
> long help texts in the complete Hungarian translation (and will do the
> updates :), I say having the text flow intact is more important then
> "helping" translators with breaking up text in smaller chunks. Having
> big chunks ensure that:
>
>
>
> * That the string will not show up in the locale cache (because of
> their size), and will not slow down pages.
> * It is easier to translate the complete texts, as you know you
> need to
> use the very same terminology around, and will not use random
> different
> translations, and you will also refrain from repeating the same
> "language salt", thus leading to quality translations
> * Users of Drupal will not be faced with half translated help chunks
> (which is especially funny, if the middle of some English text is
> translated).
>
> By the way, Drupal used to have per paragraph t(), but then changed to
> use one t(), which optimises database queries, and given the above I
> think it is better for the user and translator too.
>
>
> Just my two cents...
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 14:16:51 +0000 : killes at www.drop.org
>
> Goba, I knew you would answer like that. ;)
>
>
> I think that the single paragraphs are sufficiently selfcontained to
> translate them in pieces. I have looked at the aggregator help as an
> example.
> You yourself are a kind of an übertranslator who'd also translate the
> whole bible in one PO chunk. ;)
> So I think we should look at other translations, too.
> I am using a very nice PO editor, but I know that I will never
> translate chunks of text that are more than two or threee sentence
> long. It takes too much time. But if I can split it up, I might
> translate the small pieces one by one. And I'd also be sure that I do
> not have to change everything just because a typo was fixed in the
> original.
>
>
> The cache argument does not really count, because the pearagraphs will
> still be longer than 75 characters.
> Also you already need to know where your translation will appear to do
> any Drupal translation. that is you will see the translated paragaphs
> in contex with the non-translated parts.
>
> I agree that a half done itnerface looks funny, but its better than
> nothing.
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 14:36:42 +0000 : Goba
>
> Killes, your reasons are valid, but I still prefer the all-in-one
> approach. :) I will deal with it either way, so feel free to pick one
> way. I remember the transition from per-paragraph t()s to all-in-one
> t()s, and I think it was a good choice (and I have not heard much
> complaints, although I am not active enough in the translator
> community
> nowadays).
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 14:48:43 +0000 : killes at www.drop.org
>
> I firmly believed the reason for not getting complaints is that nobody
> even thought to translate those helptexts and is also a reason for not
> haveing many 100% translations.
>
>
> There are a number of translations that are listed as being 100%, but
> that is at least partially due to the script which makes
> http://drupal.org/translation-status
> It only counts the non-translated strings that are in the PO files in
> each directory, not the number of strings in the POT files.
>
>
> The Ukrainian translation for example is listed as being 100%, but
> there are only 10 out of 33 in the repository. Guess I should fix the
> script.
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 14:53:15 +0000 : Goba
>
> Yes, it might be a good idea to msgmerge the po files with the actual
> pot files in the same CVS branch, and then check for completeness, so
> that a proper overview is available.
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 15:55:37 +0000 : stefan nagtegaal
>
> So, now what is the plan?
>
>
> Per paragraph t()-ing or per helptext t()-ing?
> I'll volunteer for making such a patch..
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 16:02:53 +0000 : killes at www.drop.org
>
> I am changing that to cvs.
>
>
> My vote is obviously for splitting things up. PO editors were made to
> translate small pieces of text and not novels or even essays.
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Fri, 01 Jul 2005 17:59:24 +0000 : stefan nagtegaal
>
> Then, so be it Killes!
>
>
> I have to agree with you completely. Due to this (and inline with
> theme_placeholder($text), introduced lately by Steven/Dries), I'll
> come
> up with a patch which implements the helptexts, and introduce the
> following theme_* functions to get things a little easier and more
> drupalish:
>
> <?php
> function theme_text($text) {
> return "<p>$text</p>";
> }
> function theme_code($text) {
> return "<code>$text</code>";
> }
> ?>
>
>
> This makes all the <p>-tags inside the helptexts redundant and
> helps us
> to clean up the texts a little more by removing a little more HTML out
> of it.. The same with the <code>
>
>
> I am still thinking about how we should handle (un)ordered and
> definition lists, inside the helptexts.. Has someone another plan for
> this?
>
>
> Please let me know what you think about this idea. I worked a lot on
> the helptexts before, and tried even mroe times to make them better
> and
> easier to translate. Due to that, I think this is the right thing
> todo..
>
>
> But, maybe I am wrong..
>
>
> I'll still volunteer for patching core/HEAD to get this in..
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Sun, 03 Jul 2005 10:03:37 +0000 : Dries
>
> For now, let's not split each paragraph and let's not introduce new
> functions. Just fix up the patch as is.
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Tue, 05 Jul 2005 14:06:41 +0000 : cel4145
>
> Dries wrote,
>
> "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."
>
>
> I think we have to go with the assumption that if a user is changing
> menu paths then they should have some awareness that the path itself
> will no longer be valid, and as long as the paths are links, they'll
> still be able to access the correct pages.
>
> Kieran wrote,
>
>
> "9. . . . We were told to add titles for accessibility reasons. If
> this
> is not the case we can remove them."
>
>
> See Dive Into Accessibility Adding titles to links [1]:
>
>
> "Not all links should have titles. If the link text is the name of an
> article, don't add a title; the link text itself is descriptive
> enough.
> But if you read the link text by itself, out of context, and can't
> figure out what it points to, add a title."
>
>
> So the title must be more descriptive than the original link text in
> order to increase accessibility. One's that merely restate the
> original link text serve no purpose.
> [1] http://diveintoaccessibility.org/
> day_14_adding_titles_to_links.html
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Tue, 05 Jul 2005 18:18:16 +0000 : Dries
>
> Charlie: let's turn that into an official documentation guideline?
>
>
>
>
> ----------------------------------------------------------------------
> --
>
> Wed, 06 Jul 2005 03:54:29 +0000 : cel4145
>
> " let's turn that into an official documentation guideline?"
>
>
> Done. Updated documentation authoring guidelines 5a [2].
> [2] http://drupal.org/about/authoring
>
>
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://drupal3.drupal.org/pipermail/documentation/attachments/20050916/121e6064/attachment.htm
More information about the drupal-docs
mailing list