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

[rivena]

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:   rivena
 Status:       active

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


http://drupal.org/node/67808


Anisa.




rivena



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.