Help File Fixup: Taxonomy module

A few comments:
a) "The module is named after Taxonomy, the science of classification. " -- drop this. Taxonomy is a regular English word, so if someone doesn't know that word, they can look it up in a dictionary.
b) http://drupal.org/project/Modules/category/71 is a completely outdated link. And I think we don't need to mention contrib modules for taxonomy here -- how common is it to want/need contrib for taxonomy? I personally have never used a contrib taxonomy module... Let's concentrate here on what the core taxonomy module does instead.
c)+ return $output; case 'admin/structure/taxonomy':
This should be on two separate lines.
d) The uses heading is "creating content classification", but it only gives an example (which I personally think is unnecessary) of a hierarchical vocabulary, and doesn't say where to go to create that vocabulary, or how to do it, or anything about the settings, how to specify which content types it applies to, etc.. How about sticking to instructions (omitting the lengthy and I think useless example) and giving a link to the taxonomy management page?
e) There should probably also be a section in Uses on how to attach particular terms to a piece of content
f) RSS-feeds - should not be hyphenated.
g) " by navigating to the URL taxonomy/term/123. " This is not a URL, it's a Drupal path. Either make it into a URL by using example.com as the base site URL and adding "and your site is at http://example.com" to the sentence so people know what you are talking about, or don't call it a URL. Also, later in that paragraph, URL is uncapitalized once.

hey hey - if you have a chance please post a new patch with your edits, it'll help immensely! if you need help with that, hit up IRC at #drupal-contribute or #drupal-docs and get someone to walk you through it.

This is looking much better than the last time I reviewed it. A few minor things:

a) The patch itself needs a small change: indentation needs to be consistent on all lines (two spaces per level of indentation, no tabs).

b) Another minor change: I think the sentence starting "Contrary to..." that talks about free tagging should be a new paragraph (a new DD actually).

c) Typo: "they have to be made available to content type such as articles and blog entries" should say "content types"

A couple of fixes needed here:

a) When you add a Taxonomy field to a content type, you choose the vocabulary on the Field settings screen, which appears after you have created the field or if you click "edit" after the field has already been created. The screen is not called "content type settings", which is what the help text says in that last patch.

b) I also don't like where it says "You will find the field with terms in it"... If you choose a tagging widget as your editing widget for a taxonomy term, the field will not have the terms shown in it (at least until you start typing). How about just saying "The field will appear on the content editing screen..." or something like that?

c) Grammar note: The final paragraph about term and RSS -- should use future tense in things like "If (present tense) then (future tense)". So, it should say "you will find" in those sentences.

Other than that, it is looking good...

Found a few issues, rerolled...

- the example terms were difficult to scan, so I reversed the order
- removed extra space
- put comma after 'For example'
- fixed a permissions link (it was pointing to someone's local installation :-))
- Revised sentence referencing free tagging.
- Revised 'Assign vocabularies to content type' section
- Added caps to Views module

ignore, duplicate!

lisarex: That last patch didn't really get uploaded. Can you add it again, in a new comment below? Because when I click on the link to that patch, it just takes me to some d.o page, not to your patch file.

Yep, here it is again.

I think this still needs work.

a) Most of the DT headers are -ing verbs, but this one isn't "Assign vocabularies to content type".

b) "Vocabularies can also be created without terms." (talking about free tagging vocabs). I think this is misleading -- you may initially not have terms, but they certainly will have terms. The only difference is that when editing content you can add new terms on the fly.

c) I don't like the new wording in the assigning vocab to content types section:
"When the vocabularies are created, they should be made available to content types by choosing one from the Content type page".
- Why use "should" -- how about "can"...
- "When" should probably be "after"?
- "choosing one" -- it's not immediately obvious what "one" refers to until you read on in the sentence.

d) Generally, a lot of the wording seems awkward to me, but I'm not sure why... like maybe it shouldn't have "the" so much in the part about assigning terms to content?

I'm not in a place where I can easily create patches, but I'll try a rewrite and paste in a separate comment...

OK, here's my suggested rewrite of this... can't make a patch right now, but maybe someone else can? I cleaned up (I think/hope) the awkward wording, as well as a few errors of fact (like the fact that you don't make a vocabulary free tagging on the Taxonomy page, but actually on the field settings when you assign it to a content type).

+      $output = '<h3>' . t('About') . '</h3>';
+      $output .= '<p>' . t('The Taxonomy module helps classify the content of your website. To classify content you define <em>vocabularies</em> that contain related <em>terms</em>. For more information, see the online handbook entry for the <a href="@taxonomy">Taxonomy module</a>. There are also <a href="@taxcontrib">many contributed modules</a> that extend the behavior of the taxonomy module for both display and organization of terms.', array('@taxonomy' => 'http://drupal.org/handbook/modules/taxonomy/', '@taxcontrib' => 'http://drupal.org/project/modules?filters=tid:71&solrsort=sis_project_release_usage%20desc')) . '</p>';
+      $output .= '<h3>' . t('Uses') . '</h3>';
+      $output .= '<dl>'; 
+      $output .= '<dt>' . t('Creating classification systems') . '</dt>'; 
+      $output .= '<dd>' . t('Users with sufficient <a href="@perm">permissions</a> can create classification systems (called <em>vocabularies</em>) from the <a href="@taxo">Taxonomy page</a>. After creating a vocabulary, you can then add <em>terms</em> to the vocabulary, and use a drag-and-drop interface to control the order of terms and create a term/sub-term hierarchy. For instance, you might create a vocabulary for classifying music by genre with the following structure:', array('@taxo' => url('admin/structure/taxonomy'), '@perm' => url('admin/config/people/permissions', array('fragment'=>'module-taxonomy'))));
+      $output .= '<ul><li>' . t ('<em>vocabulary</em>: Music'); '</li>';
+      $output .= '<ul><li>' . t('<em>term</em>: Jazz') . '</li>';
+      $output .= '<ul><li>' . t('<em>sub-term</em>: Swing') . '</li>';
+      $output .= '<li>' . t('<em>sub-term</em>: Fusion') . '</li></ul></ul>';
+      $output .= '<ul><li>' . t('<em>term</em>: Rock') . '</li>';
+      $output .= '<ul><li>' . t('<em>sub-term</em>: Country rock') . '</li>';
+      $output .= '<li>' . t('<em>sub-term</em>: Hard rock') . '</li></ul></ul></ul>';
+      $output .= t('You can assign a sub-term to multiple parent terms. For example, <em>fusion</em> can be assigned to both <em>rock</em> and <em>jazz</em>.') . '</dd>';
+      $output .= '<dt>' . t('Assigning vocabularies to content types') . '</dt>'; 
+      $output .= '<dd>' . t('In order to use a vocabulary to classify a particular type of content, you need to add it as a field on the content type from the <a href="@ctedit">Content type page</a>. To do this, click on the <em>Manage fields</em> link or tab on the desired content type, and add a field of type <em>Taxonomy term</em>. You have your choice of several widgets to use to select which terms to assign to a piece of content on the editing screens, including select lists and free tagging fields; selecting a free tagging field allows the person editing the content to add terms to the vocabulary by typing them into the field, rather than having to visit the taxonomy management page. After you add the taxonomy field to the content type, you will be able to select the vocabulary on the field settings page.' . '</dd>', array('@ctedit' => url('admin/structure/types')));
+      $output .= '<dt>' . t('Classifying content') . '</dt>'; 
+      $output .= '<dd>' . t('After a taxonomy field is added to a content type, you can start classifying content. The field will appear on the content editing screen when you edit or <a href="@addnode">create content</a>.', array('@addnode' => url('node/add'))) . '</dd>';
+      $output .= '<dt>' . t('Viewing content and RSS feeds by terms') . '</dt>'; 
+      $output .= '<dd>' . t('The Taxonomy module automatically generates pages and RSS feeds listing content that has been assigned to taxonomy terms. For example, if the taxonomy term <em>country rock</em> has id 123, the page will be at path <em>taxonomy/term/123</em>, and the RSS feed will be at path <em>taxonomy/term/123/feed</em>. Taxonomy is fully integrated in the contributed module <a href="@views">Views</a>, which allows you to generate custom lists of content.', array('@views' => 'http://drupal.org/project/views')) . '</dd>';
+      return $output;    

bangpound -- I didn't see your comments before I attached my comment. What do you think of that version?

- changed use title "Creating content classification" to "Classifying content"
- changed "social bookmarking applications" to "photo management applications" since it's a more common use
- tried to clean up a lot of the language just to make this less confusing
- for what it's worth, i think the example using music genres may be really useless to certain user groups, and should possibly be removed altogether (since we did not allow this sort of example in the forum help, it was moved to be on one of the forum config pages)
- made all "use" titles to use active language "xing your y"
- removed the part about being integrated with views, TMI
- am tempted to remove the stuff about term listing paths and RSS paths, again TMI...leaving for now. Added "You can also navigate to the listing page by clicking on a linked term anywhere in the site." as most people will not type in the URL.
- moved help hook to top of .module file

New patch, but this still needs work/review. @bangpound will look at it later today

what the frak.

@bangpound you seem to know a lot more about what is going on, so i'm really hoping you can re-roll a patch with your input in the next couple days - i'll keep an eye on this to review whatever you put up, but am gonna stop hacking at it for now!

Just for the record, I don't agree with what bangpound is saying about taxonomy and fields in #21 and #24.

The process to add taxonomy to a content type is:
a) Create a vocab on the taxonomy page, and possibly add terms to it there
b) Find the content type on the content types page, and get to its manage fields page
c) Add a new field, of type Taxonomy. On the config page, choose the vocab the field applies to.

Creating a vocabulary does not make a field available automatically to the content type. You have to go through the add field process to define how you want the taxonomy to behave as a field. You don't use the "add existing field" section, you have to use "add new field". So I think saying that it makes a taxonomy field "available" would be misleading and confusing.

Just a note about the last patch: indentation issues!

i don't think you rolled your patch from the root dir, and i'm not sure i'm clear on what taxo is doing or supposed to be doing, but i'm gonna try and review this anyway!

@bangpound - Iam sorry I dont know enough PHP to roll a new patch but here are some comments.

What does "sufficient privileges" mean. If I was a beginning use I am not sure this would mean anything me. I think that will the "appropriate permissions" might be clearer.

"The page listing the terms provides" - this should be a link or should we make a more fundamental change to the paragraph so that we do not need to lino to the same page twice.

For - 'Terms in a free-tagging vocabulary can be built gradually as you create or edit content. This is often done used for blogs or photo management applications. how about 'Terms in a free-tagging vocabulary can be added to as needed by users with appropriate permissions when they add or edit content. Drupal will dynamically show users terms once they are added with an autocomplete widget. Free-tagging is often used for blogs or photo management implementations of Drupal.'

"with your other site content" should be something more like with the content on your site or with your site's content.

Once again I am sorry I can not roll a patch for this. I hope this can help.

@bangpound my comments still stand.

i got halfway through a review/update last night - will get to the rest sometime today (monday's are my busiest at work, so might not be till later on)

@bangpound - so, based on this, does any of the content of your text need any major changes?

otherwise, i'll just do a cleanup (and incorporate some of @denverdataman's comments as appropriate).

- attempted to clean up the views/rss section a bit more
- standardized other bits of language
-also changed this, which had some funny language:
case 'admin/structure/taxonomy/add':
"Tags allows users to create terms when submitting posts by typing a comma separated list." --> "Free-tagging allows users to create terms when submitting posts by typing a comma separated list."

i think this looks pretty darned good, assuming all the functional changes have been reflected, RTBC.

ack, well nevermind then :-p

We're not using the word "post" for content...

Anyway, guess we need to wait and see on that taxonomy issue.

I do not think that taxonomy issue is going to be finished by tomorrow, since there is no viable patch yet.

Ummm...

The latest help for admin/structure/taxonomy/add said:
"Define how your vocabulary will be presented to administrators and users, and which content types to categorize with it. Free-tagging allows users to create terms when submitting content by typing a comma separated list. Otherwise terms are chosen from a select list and can only be created by users with the "administer taxonomy" permission."

However, in reality that page currently only allows you to choose a taxonomy name and description. The stuff about free tagging etc. is configured in the Field.

Anyway, here's a new patch.

arianek reviewed this via IRC... I think it's been reviewed enough now.

Wow, great job on this tweaky-assed page, everyone! :D

The only thing that I don't see covered here is the fact that you can actually add terms to any fieldable entity, not just content types. In core right now this means users, content types, and even other taxonomy terms for maximum mind-screwage. :P However, since all of this stuff is a bit in flux atm, and it's relatively advanced usage anyway and doesn't relate to understanding what taxonomy is, I agree with this as a good solid base, and we can make further refinements as bug fixes if we need to.

Committed to HEAD!