[documentation] [Documentation feature] taxonomy pages rewrite/reorganization

[Gary Feldman]

Issue status update for 
http://drupal.org/node/67616
Post a follow up: 
http://drupal.org/project/comments/add/67616

 Project:      Documentation
 Version:      <none>
 Component:    Admin Guide
 Category:     feature requests
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  rivena
 Updated by:   Gary Feldman
 Status:       active

"
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




Gary Feldman



Previous comments:
------------------------------------------------------------------------

Tue, 06 Jun 2006 19:25:13 +0000 : rivena

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.




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

Wed, 07 Jun 2006 18:56:56 +0000 : rivena

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.




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

Wed, 07 Jun 2006 19:04:31 +0000 : rivena

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


http://drupal.org/node/67808


Anisa.