A long-standing issue with synchronizing the module help in admin/help/module_name with that in http://drupal.org/handbook/modules are those darn "You can" links at the bottom that say things like:

You can

The problem is we can't link to actual paths on Drupal.org, since they will be 404s/403s in many cases, which totally befuddled and frustrated users. And we made many attempts of encoding these in an arcane way so that they could be parsed out with a script, but that was also cumbersome and only ever done for the core pages, not contrib.

Now that 5.0 has the "administer by modules" page, can we safely remove these links from core help and the admin help text in the handbook documentation?

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Gábor Hojtsy’s picture

Question is if these "you can" lists really overlap with the new per module admin pages. I am not sure. But by the way, these lists were hard to translate too (we need to strictly look at the menu item translations when translating these strings).

webchick’s picture

A very good question. Not 100%. But about 85% at least.

Missing portions are:
- All node modules have links to "create content" which are not found in administer by module.
- Some modules link off to pages their modules create or add to. For example, contact module's help page links to the contact form, blog module's help page links to "my account."

In all other cases, it's the "administer >> something" links.

We could do two things to increase that 85% to 100%:

1. Include an administration link to "create content" for all node types in the "administer by modules" page.
2. Move references to "oddball" links like "my account" and such to the actual body text, rather than the "You can" section.

In fact, I think I'll go ahead and roll a patch for #1 right now.

webchick’s picture

Title: For discussion: Should we remove the "You can" links from module help? » Remove the "You can" links from module help?
Project: Documentation » Drupal core
Version: » 5.x-dev
Component: Documentation in CVS » other
Priority: Normal » Critical

Patch for #1: http://drupal.org/node/97812 .. please review.

Since these links are a pain in the butt for translators, and they're a pain in the butt for documentors, this is now no longer up for discussion. ;) Rolling a patch to remove these links from the help text.

Marking critical because it blocks the string freeze.

webchick’s picture

Status: Active » Needs review
FileSize
58.52 KB

Here we go. Dun dun dunnnn....

There will be a massive amount of clean-up to the docs that needs to happen after this gets in, but I figured I'd keep it simple for now.

Dries’s picture

I agree that these links are a lot less valuable nowadays. The new admin layout is far superior (and no one really reads the documentation anyway).

+1 for removing these ...

pwolanin’s picture

+1, for removing these though this suggests a need to keep the relevant handbook pages up to date with per-version info (especially with the admin interface change)

pwolanin’s picture

related issues for help text improvement per devel list:

http://drupal.org/node/97889

http://drupal.org/node/97894

http://drupal.org/node/97897

webchick’s picture

Status: Needs review » Reviewed & tested by the community

I'm going to be bold... the patch is very simple; only removes stuff that we all agree should be removed.

kkaefer’s picture

+1 for this patch. The "You can" links really caused a lot of headache in translation.

drumm’s picture

Status: Reviewed & tested by the community » Needs work

The by module admin page's system is much better. However, the old 'you can' system does have one distinct advantage, putting the links next to the help. I'd like to see the void left by the hard-to-maintain 'you can' links replaced with a helpful copy of the relevant list of administration pages which I assume can be auto-generated.

webchick’s picture

Status: Needs work » Needs review

Hm.. I can do that, but it would require either an API change or else duplicating most of the code in system_admin_by_module. The same links are also then in two places... are we sure that's what we want?

Dries’s picture

I say we want to commit this patch, and worry about the rest later. :-)

pwolanin’s picture

For the block module I think you cut one line too many- you cut here (and in no other module) the line starting 'For more information...'

drumm’s picture

FileSize
61.24 KB

I just did a little refactoring in system module and put some links up on the help pages. If there was some specific reason for wording it "You can," let me know, because I changed it to "@module administration pages."

pwolanin’s picture

Status: Needs review » Needs work

still cuts one line too many in block module help text.

neclimdul’s picture

Status: Needs work » Needs review
FileSize
58.35 KB

Same patch as drumm's but with the missing line pwolanin pointed out.

neclimdul’s picture

didn't catch user.module not applying cleanly in drumms patch and accidentally dropped its changes.

*This* is the same as drumm's patch with the block.module line.

neclimdul’s picture

FileSize
61.08 KB

I'm a real idiot... ok. and this one doesn't have my modifications.

webchick’s picture

Title: Remove the "You can" links from module help? » String freeze: Remove the "You can" links from module help
Status: Needs review » Reviewed & tested by the community

Wicked! This looks ready to go to me!

Dries’s picture

Status: Reviewed & tested by the community » Fixed

Good stuff! Committed to CVS HEAD. Thanks.

Anonymous’s picture

Status: Fixed » Closed (fixed)