[drupal-devel] [task] Admin help in core modules

Fri Jul 1 15:55:38 UTC 2005

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:   stefan nagtegaal
 Status:       patch

So, now what is the plan?

Per paragraph t()-ing or per helptext t()-ing?
I'll volunteer for making such a patch..

stefan nagtegaal

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 :).

------------------------------------------------------------------------

July 1, 2005 - 15:38 : 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.

------------------------------------------------------------------------

July 1, 2005 - 15:50 : 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...

------------------------------------------------------------------------

July 1, 2005 - 16:16 : 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.

------------------------------------------------------------------------

July 1, 2005 - 16:36 : 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).

------------------------------------------------------------------------

July 1, 2005 - 16:48 : 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.

------------------------------------------------------------------------

July 1, 2005 - 16:53 : 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.