All or at least most of the tokens for the node module, in node.tokens.inc, use the word "node" in their human-readable description.
This is wrong. There has been a lot of care in the Drupal 7 UI to not use the word "node" to refer to nodes. Ever. The permissions don't refer to this, the content management screens don't, etc. So the token descriptions also should not.
Don't use the word "post" either.
The term being used is "item of content" or something like that. Perhaps the usability team has a better answer to how these things should be worded?
Anyway, the terms currently being used are things like:
The unique ID of the node.
The unique ID of the node's latest revision.
The unique ID of the user who posted the node.
etc.
Comment | File | Size | Author |
---|---|---|---|
#11 | 678012.patch | 932 bytes | jhodgdon |
#5 | 678012_node_die_die_die_die.patch | 6.21 KB | gdd |
#4 | 678012_node_die_die_die_die.patch | 6.15 KB | gdd |
#3 | 678012.patch | 3.72 KB | jhodgdon |
Comments
Comment #1
jhodgdonclarifying the title.
Comment #2
jhodgdonGuideline reference: http://drupal.org/node/604342
Comment #3
jhodgdonHere's a patch - definitely needs review!
Comment #4
gddUpdated to include the new docs from system.api.php so they all match
Comment #5
gddAnd a new patch because somewhere we lost a lot of periods at the end of sentences.
Comment #6
jhodgdonToken descriptions are not sentences. Why do they need periods? We don't have periods at the end of permission descriptions, e.g.?
Comment #7
jhodgdonAnyway, of course you are right that I shouldn't have just removed the periods just becasuse I think they are stupid. :)
I like your patch, and thanks for patching up the hook_token* examples as well.
Comment #8
webchickHmmmmmmmmmmmmm. I am torn on this patch.
On the one hand, I do agree that we have this policy, for better or for worse, of removing "node" in favour of "content" everywhere in the interface.
On the other, I think that using that /here/ is going to be just terribly confusing. The tokens themselves are things like [node:title], and this would make the labels mis-match the tokens they refer to. It is too late to change that at this stage, and I actually don't think we should change it because it's important for tokens to be clear about exactly what data they're referencing. In this context, "Node ID" is actually much more clear than "Content ID".
Furthermore, since not all of CCK was moved into core, it will still exist in contrib in D7. Since its main module is content.module, the tokens it exposes will likely have the "content" namespace. Now it becomes impossible to differentiate between "Content" module and "Node" module tokens.
Therefore, I think this issue is a won't fix from me. But I'll leave it open for discussion in case someone has a compromise suggestion.
Comment #9
jhodgdonIf we leave the token descriptions as-is, then we absolutely must somewhere in the help text define the term "node", because we've been very very very careful never anywhere else in the entitre D7 help text and UI to ever use the term "node". To me, leaving these as saying "node" is really jarring, after having to awkwardly reword all kinds of other stuff to say "content item". I don't understand the rational for not changing it in this one remaining place.
Then again I think it was a poor decision to try to eliminate the word "node" from the UI in the first place, because it did make a LOT of stuff really awkward.
Comment #10
webchickI definitely agree that it's jarring for new users who don't know what a node is. But I think those WTFs renaming these to variations of "content" would cause are insurmountable. Tokens are a weird area that expose parts of our API directly to users (similar to Views). I guess the saving grace is that in most places, these will only be used by the person wearing the site builder hat, rather than the content editor hat (except for things like e-mail templates). :\ We do expose the word "Node" in our help index, so they can go there for a bit of help. I agree that's not ideal, though.
Ok, what about this?
- 'name' => t('Nodes'),
- 'description' => t('Tokens related to individual nodes.'),
+ 'name' => t('Content'),
+ 'description' => t('Tokens related to content items.'),
+ 'name' => t("Content ID"),
+ 'description' => t("The unique ID of the content item."),
Leave the name of both of these with "node" in the name. IMO we have to do that, because otherwise it's inaccurate.
Replace awkward "Content item" with just "content." For example, "The content's unique ID". It's rare that a node token refers to one particular node, and more often about all nodes.
Comment #11
jhodgdonHow about if the description of the page is 'Tokens related to content items, also known as "nodes"', and then we can leave the rest as-is? Except that the description doesn't necessarily appear in the UI with the tokens, does it?
OK. How about if we just define "node" in the overall description and in the first item description, and leave it as "node" elsewhere?
And by the way, I checked and core D7 is not even displaying tokens/descriptions anywhere (the only place that even uses them is in user.module for automated email sending, but it has its own methods and doesn't display descriptions).
So this will "only" affect the user experience of contributed modules, such as Path Auto, which nearly all smaller Drupal installations use.
Anyway, here's a more limited patch, which leaves most of the "node" words as-is, but attempts to at least define the word.
And I don't think I want to add this to the hook_token_info example implementation, because it is so lame. Is that OK?
Comment #12
lisarex CreditAttribution: lisarex commentedLooks good to me (reviewed patch with eyes, since it's a non UI-patch)
RTBC?
Comment #13
webchickYep, I can definitely live with this. Thanks, jhodgdon!
Committed to HEAD.