I've thought this for a long time, but wouldn't be neat if the handbook were like drupal code? Each page a little essential function, complete in and of itself. When it needed another function, it would reference another page, rather than be redundant and make more code.

Looking at the taxonomy pages (http://drupal.org/handbook/modules/taxonomy) reminded me of that; there were three different places where it described different kinds of vocabulary structures, but they were written from 3 different perspectives that make it difficult to extract.

So, I suggest a rewrite that creates more little pages that are focused on one specific topic. If there is additional material, let that be another page. My suggested outline:

---------------
Taxonomy main page: Should be cut down. More 'you can's. Less self promotion, and add some basic description about each kind of vocabulary function. Lingo used should be standardized (discussion needed).

Different kinds of vocabularies (flat, hierarchical, free tagging)

HOWTO: Create a vocabulary

HOWTO: Create a term

Contributed modules comparison (Taxonomy Garden) (should clearly state that these are contrib, not core, that some may not be updated, modules whose function has been put into core should be removed)

Useful code snippets

More on Taxonomy (storytelling/Long version; all techincal details should be left to other pages; this should be about case examples and detailed explanation, what about an introduction, and then at least 3 case examples of when it's appropriate to use a kind of vocabulary?)

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

Anyway, just a thought. The main thing is to reduce redundancies and make it more clear to the end user what each page is for. Each page should be able to function independantly, without restating what another page says. I started re-writing the taxonomy main page, will put that through later.

Anisa.

Comments

rivena’s picture

rivena commented

Here is a rough draft of the main taxonomy page (keeping in mind this is also the admin help).

I am not really happy with this, I would like to see short definitions and brief examples of each taxonomy type. I also think the terms we use here should be standardized. Do we call it a category or a term or is a category a vocabulary? It is very confusing. Mostly I took out the abundance of the word hierarchy. ^.^:

Rewrite of this page: http://drupal.org/handbook/modules/taxonomy

-----------------------
You can use the taxonomy module to categorize content by topic (category). Possibilities are endless, but include using categories for site navigation, or organizing a list of music reviews by musical genre.

Each topic tag (category or term) is part of a vocabulary. Drupal allows you to tag each piece of content (blog, story, etc.) using one or many of these terms. You can choose to have no relationship between terms in a vocabulary (all terms equal), or create a hierarchy between them (category – sub category). You can also define related terms (category 1 is related to category b).

Most vocabularies are controlled, the administrator or moderator creates the categories, and ordinary users select from their available options. By checking the "Free tagging" option when creating a vocabulary, however, users can create and enter their own tags for their content.
See the handbook pages for detailed examples.
You can
• add a vocabulary at administer >> categories >> add vocabulary.
• administer categories at administer >> categories.
----------------------------------------

Please let me know what you think and add and subtract. This page is very important for new and old users, so it needs to be as clear and concise as possible.

Anisa.

rivena’s picture

rivena commented

Users are confused by all that lingo in the taxonomy docs:

http://drupal.org/node/67808

Anisa.

Gary Feldman’s picture

Gary Feldman commented

if the handbook were like drupal code? Each page a little essential function, complete in and of itself.

That's fine for reference pages, but trickier for pages that are more like tutorial, how-to, or users guide pages.

Users are confused by all that lingo in the taxonomy docs:

Agreed. The single biggest improvement to the module (both code and docs) would be to eliminate all the redundant, sometimes conflicting terminology. Unfortunately, the taxonomy module is such an important selling point for Drupal that removing that word is questionable, even though it's the worst of the bunch for clarity.

It seems to me that the choices are

  • taxonomy, vocabulary, categories for the collections, and possibly tag collection
  • category, term, tag, keywords for the individual words

Here's a possible example. Boldface indicates a link to another page. I've tried to stick to vocabulary and tag as the only jargon used, except for the name of the module. If I use a different term anywhere, that's inadvertant and should be fixed.

-----
The taxonomy module is a general purpose tagging module that can be used in a variety of ways. A tag is just a word or phrase that can be associated with one or more nodes. Likewise, a node can be associated with one or more tags. Tags are organized into collections called vocabularies.

This seems like a simple idea, but is very powerful because there are so many different ways to use these vocabularies. It is perfectly possible, for example, to use one vocabulary just to control access and an entirely different vocabulary to simplify searching. There are specific applications of vocabularies, as these examples show, but there are also some common patterns of usage that can be adapted for various applications. Three of the most important of these usage patterns are flat, hierarchical, and free tagging.

The mechanics of defining and administering vocabularies and tags are the same, regardless of how you use them. The significance of a particular vocabulary might be something you just implement by following a convention (e.g. a convention that says every page must be tagged with exactly one of beginner, intermediate, or advanced.) Or it might be something connected to a separate module, such as the taxonomy_access module. We suggest you begin by looking at the mechanics, without first worrying about how to take advantage of it, and then go on to read some of the common usage patterns and applications below. When you're ready, you might look at some of the more advanced or specialized applications of this module.
-----

Then go on with a bullet list showing each of these patterns, and possibly others. Each bullet item would include a sentence or sentence fragment (no more than one sentence) describing the item, and including a link to a page discussing that particular item. A separate section would either have a bullet list of advanced applications, or else a link to a separate page introducing the advanced applications.

Gary

rivena’s picture

rivena commented

Thank you for your comments!

Unfortunately, the taxonomy module is such an important selling point for Drupal that removing that word is questionable, even though it's the worst of the bunch for clarity.

The word taxonomy itself? I dunno, the more people say it's confusing, the more I think what's the big deal. As long as you explain it once and use it consistently, there shouldn't be too many problems. One point of confusion is everyone is talking about taxonomy, but the actual thing in the settings is 'categories'.

taxonomy, vocabulary, categories for the collections, and possibly tag collection
category, term, tag, keywords for the individual words

I would reserve taxonomy for talking about either the module or the whole idea of tagging.

I wonder if this is would work:

  • use vocabulary as the technical term, users can understand this as a category.
  • use term as the technical term, users can understand this as a tag.

    Keywords sounds a bit like search keywords, is not widely used, and I would avoid it.

    This seems like a simple idea, but is very powerful because there are so many different ways to use these vocabularies. It is perfectly possible, for example, to use one vocabulary just to control access and an entirely different vocabulary to simplify searching.

    Drupal doesn't come with taxonomy access, I would avoid all reference here. Kieran had a survey thingy about what the most common uses of taxonomy were, those would make good examples.

    There are specific applications of vocabularies, as these examples show, but there are also some common patterns of usage that can be adapted for various applications. Three of the most important of these usage patterns are flat, hierarchical, and free tagging.

    I am not entirely sure what distinction you are making. How about this:

    There are three kinds of vocabularies: flat, hierarchical, and free tagging. Which one you chose and how you use it is up to you. Irregardless, the mechanics of defining and administering vocabularies and tags are the same.

    Before you use this module in your site, it is recommended that you get used to creating, editing, and deleting vocabularies and terms. Read through the following brief examples, and once you have a good idea of what kind of category you want to set up and how you want to use it, you might look at some of the more advanced or specialized applications of this module.

    I am not too sure about that last one... but I totally agree with the brief examples thingy.

    Anisa.

    • add1sun’s picture

    add1sun commented
    Category: feature » task
    Priority: Normal » Critical

    This is an old issue but still needs some serious attention, especially with D6 around the corner and in light of this patch and discussion: http://drupal.org/node/192209.

    Currently the main taxonomy page refers to it as the "Categories module" for jiminy's sake.

    sepeck’s picture

    sepeck commented

    I missed that edit. That occurred in an April edit by a contributor. Corrected that one part only.

    Until the taxonomy/category naming is cleared up (Is it cleared up?) it will be difficult to actually chart a path.

    add1sun’s picture

    add1sun commented

    The patch in my previous comment has been committed so I dare say it is cleared up as far as core D6 is concerned.

    anschinsan’s picture

    anschinsan commented
    Project: Documentation » Drupal core
    Version: » 7.x-dev
    Component: Admin Guide » documentation
    dcor’s picture

    dcor commented
    Priority: Critical » Minor
    jhodgdon’s picture

    jhodgdon
    she/her
    Primary language English
    commented
    Project: Drupal core » Documentation
    Version: 7.x-dev »
    Component: documentation » Correction/Clarification

    Someone had moved this into the wrong queue

    leehunter’s picture

    leehunter commented
    Status: Active » Fixed

    I'm marking this as fixed. Not that the taxonomy docs don't still need work, but I think there's been too long without activity on the OPs original issue. Someone could open a new issue if they have a vision for how to fix up that section (or just go ahead and do it)

    Status: Fixed » Closed (fixed)

    Automatically closed -- issue fixed for 2 weeks with no activity.