[wp-docs] New to list

Wed Jul 8 22:44:01 UTC 2009

I know we thoroughly documented the categories structure and guidelines, but
I can't find them where they are supposed to be. So I fixed it on the
following pages:

http://codex.wordpress.org/Codex:Guidelines#Codex_Categories

http://codex.wordpress.org/Help:Editing#Categories

http://codex.wordpress.org/Codex:Maintenance

I also spent some time going over the
http://codex.wordpress.org/Special:Categories list and wanted to cry - the
same emotion I feel every time I go to that page and find that all our
beautiful work has been mangled again.

Here are the conventions and we need folks to start digging in and fixing
these.

1. All categories must have Capital Letters not lower case as MediaWiki
treats "WordPress Lessons" and "wordpress lessons" and "WordPress lessons"
as three different pages. All pages with the lower case versions must have
their categories changed to the appropriate cap version.

2. All foreign language pages must be categorized with their proper foreign
category name, with the two letter language code in front of the category
name, per the example in the Guidelines. The only exception is the country
or language specific main category.

This two prong system does two important things. First, it groups all
content into a specific "Codex section" for that language and second, it
puts all language specific content in that language code. So if you click
the French Codex category, you will find all the documents in French. If you
click the fr:Panneaux_Administration, you will find all the articles about
the Administration Panels in French. If you don't speak the language, at
least try to recognize the language enough to get it in the right Codex
language section to help out those volunteers.

3. Keep Categories SPECIFIC and matched to the Table of Contents and
WordPress features. As outlined in the guidelines, the categories need to be
in keeping with the current table of contents as much as possible. I'm
working on a total restructing of the table of contents, but keep finding
myself distracted with the never ending clean up of content, so your help in
grouping things by category and cleaning as you go will help the TOC efforts
dramatically. I'd love to find a way to do all our TOC by categories
automatically. Still hunting for a MediaWiki solution - hint hint!

4. Fear NOT Overcategorization: For right now, I'd rather see the content in
many related categories rather than only a few. Use your best judgment, and
be specific, but let's make sure we help users find the information without
being overwhelmed. Check a category to see if it is appropriate, as well as
overloaded or not, if it helps you to decide where a document should be
placed.

5. Categorize the Uncategorized: Check
http://codex.wordpress.org/Category:Uncategorized for uncategorized content
and start categorizing.

6. Check each category in the
http://codex.wordpress.org/Special:Categoriesto ensure the articles
within it are categorized appropriately.

7. Why not add category links when appropriate within the content? To make a
link in the content to a category, use a colon in front of the word
"Category" such as [[:Category:WordPress_Lessons|WordPress Lessons
category]] to guide people to related content.

And please tell me who to shoot that came up with UI Link as a category
name. Do not make me tell you why it sucks as a category name. There are 56
pages that have to be changed to something more appropriate like
Administration Panels. SIGH.

Once we've moved all the inappropriate categories to proper categories (you
should be able to tell the diff, such as wrongly capped categories and bad
category names), and they read zero members, let me know and I'll delete
them. We don't need to do redirects on any of those as I don't think many
are linking to categories. I'll check for backlinks before deleting them.

This can be part of the boring work of volunteering on the Codex, but it is
the most important work, too. The better we can categorize the content, the
better we can help users find the information they need.

Once we get these cleaned up, I'll also make a category "cloud" unless we
can find an add-on or extension that will do that automatically. There must
be auto things like this by now, isn't there?

RED LINKS
I've just noticed that the red links indicative of a page with no content
aren't working. HOW did I miss THAT? I've asked that the red link style be
added back to help us find the links to pages without content so we can fix
that.

SNARK ALERT
While going through some of the documents to write the guidelines and check
out the categories, I found some snarky comments in the docs. They are
subtle but there. Pay close attention to any snarky comments and help clean
those out, please, if you find them.

They are usually things phrased like, "If you want a better way to do this,
see this..." leading to an external link, or "..but it doesn't always work"
which isn't helpful nor informative since there isn't an explanation as to
why or alternatives. These are just subtle "editorial comments" but also
look out for snark comments that are more accusatory. The WordPress Codex is
pretty strict on the editorial guidelines keeping the "I" out of the
documentation and being neutral but enthusiastic in tone, so help us keep
any little snarky commentaries out. Thanks.

Thanks to all! And thanks for cacthing this issue about the lack of category
guidelines. I am sure that MichaelH and the rest of the team came up with
those a few years ago. We worked so hard on setting up the categories in the
first place. Odd. So thanks for noticing.

Lorelle VanFossen

On Wed, Jul 8, 2009 at 11:34 AM, Charles E. Frees-Melvin <charles at cefm.ca>
wrote:
>
> The search is not great, or should I say the search in the theme. If you
know mediawiki and can get to it's search page it's 6000% better.
>
> ---
>
> Sent from my iPhone
>
> On 2009-07-08, at 15:10, Will Kemp <Will at Swaggie.net> wrote:
>
>> On 07/08/2009 06:25 PM, Lorelle VanFossen wrote:
>>>
>>> As everyone has said, welcome to the Codex and WordPress Documentation
Team.
>>
>> Thanks.
>>
>>> Be sure and check out the guidelines for editing and working with the
>>> Codex under the Community Portal. These will help you figure out how it
>>> all works.
>>
>> That was the first thing i did!
>>
>>> * Ensure EVERY page on the Codex has the proper Category at the bottom
>>> of each page. A page can be in more than one category, but we have to be
>>> REALLY specific about categorizing the documents.
>>
>> Are there any category guidelines anywhere? I've looked, but i haven't
found it.
>>
>> I'm happy to spend as much time as i can going through the codex and
categorizing articles. It will be a good way to get to know what's in there,
anyway.
>>
>>> A document on Plugins
>>> should go in the Plugins category, but if it is really basic, it should
>>> also go in WordPress Lessons, but if complicated and very "developer"
>>> then it also needs a cross reference in the Developer category, right?
>>> It's a tough call sometimes but think about how the user will hunt for
>>> the information and sort accordingly.
>>
>> For development type subjects, at least, i think the categories may need
to be more fine grained than that if they're going to be really useful.
>>
>>> * Foreign Language articles - We need to put the articles in different
>>> languages into their own language specific categories.  That will help
>>> get those articles into their own grouping, and help us get that
>>> information to the people who need it.
>>
>> If non-English languages are going to be in their own categories, surely
English language articles need to be categorized "English"? Maybe i've
missed something, but that doesn't appear to be happening.
>>
>>> Check the categorization and
>>> language guidelines for how to categorized those.
>>
>> Where are they? (Is it just me that can't find anything in this wiki?)
>>
>> Will
>> _______________________________________________
>> wp-docs mailing list
>> wp-docs at lists.automattic.comI know we thoroughly documented the
categories structure and guidelines, but I can't find them where they are
supposed to be. So I fixed it on the following pages:

http://codex.wordpress.org/Codex:Guidelines#Codex_Categories

http://codex.wordpress.org/Help:Editing#Categories

http://codex.wordpress.org/Codex:Maintenance

I also spent some time going over the
http://codex.wordpress.org/Special:Categories list and wanted to cry - the
same emotion I feel every time I go to that page and find that all our
beautiful work has been mangled again.

Here are the conventions and we need folks to start digging in and fixing
these.

1. All categories must have Capital Letters not lower case as MediaWiki
treats "WordPress Lessons" and "wordpress lessons" and "WordPress lessons"
as three different pages. All pages with the lower case versions must have
their categories changed to the cap version.

2. All foreign language pages must be categorized with their proper foreign
category name, with the two letter language code in front of the category
name, per the example in the Guidelines. The only exception is the country
or language specific main category. That does two important things. First,
it groups all content into a specific "Codex section" for that language and
second, it puts all language specific content in that language code. So if
you click the French Codex category, you will find all the documents in
French. If you click the fr:Panneaux_Administration, you will find all the
articles about the Administration Panels in French. If you don't speak the
language, at least try to recognize the language enough to get it in the
right Codex language section to help out those volunteers.

3. Keep Categories SPECIFIC and matched to the Table of Contents and
WordPress features. As outlined in the guidelines, the categories need to be
in keeping with the current table of contents as much as possible. I'm
working on a total restructing of the table of contents, but keep finding
myself distracted with the never ending clean up of content, so your help in
grouping things by category and cleaning as you go will help the TOC efforts
dramatically.

4. Fear NOT Overcategorization: For right now, I'd rather see the content in
many related categories rather than only a few. Use your best judgment, and
be specific, but let's make sure we help users find the information without
being overwhelmed. Check a category to see if it is appropriate, as well as
overloaded or not, if it helps you to decide where a document should be
placed.

5. Categorize the Uncategorized: Check
http://codex.wordpress.org/Category:*Uncategorized
for *

Lorelle VanFossen

On Wed, Jul 8, 2009 at 11:34 AM, Charles E. Frees-Melvin <charles at cefm.ca>wrote:

> The search is not great, or should I say the search in the theme. If you
> know mediawiki and can get to it's search page it's 6000% better.
>
> ---
>
> Sent from my iPhone
>
> On 2009-07-08, at 15:10, Will Kemp <Will at Swaggie.net> wrote:
>
>  On 07/08/2009 06:25 PM, Lorelle VanFossen wrote:
>>
>>> As everyone has said, welcome to the Codex and WordPress Documentation
>>> Team.
>>>
>>
>> Thanks.
>>
>>  Be sure and check out the guidelines for editing and working with the
>>> Codex under the Community Portal. These will help you figure out how it
>>> all works.
>>>
>>
>> That was the first thing i did!
>>
>>  * Ensure EVERY page on the Codex has the proper Category at the bottom
>>> of each page. A page can be in more than one category, but we have to be
>>> REALLY specific about categorizing the documents.
>>>
>>
>> Are there any category guidelines anywhere? I've looked, but i haven't
>> found it.
>>
>> I'm happy to spend as much time as i can going through the codex and
>> categorizing articles. It will be a good way to get to know what's in there,
>> anyway.
>>
>>  A document on Plugins
>>> should go in the Plugins category, but if it is really basic, it should
>>> also go in WordPress Lessons, but if complicated and very "developer"
>>> then it also needs a cross reference in the Developer category, right?
>>> It's a tough call sometimes but think about how the user will hunt for
>>> the information and sort accordingly.
>>>
>>
>> For development type subjects, at least, i think the categories may need
>> to be more fine grained than that if they're going to be really useful.
>>
>>  * Foreign Language articles - We need to put the articles in different
>>> languages into their own language specific categories.  That will help
>>> get those articles into their own grouping, and help us get that
>>> information to the people who need it.
>>>
>>
>> If non-English languages are going to be in their own categories, surely
>> English language articles need to be categorized "English"? Maybe i've
>> missed something, but that doesn't appear to be happening.
>>
>>  Check the categorization and
>>> language guidelines for how to categorized those.
>>>
>>
>> Where are they? (Is it just me that can't find anything in this wiki?)
>>
>> Will
>> _______________________________________________
>> wp-docs mailing list
>> wp-docs at lists.automattic.com
>> http://lists.automattic.com/mailman/listinfo/wp-docs
>>
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>

>> http://lists.automattic.com/mailman/listinfo/wp-docs
>
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.automattic.com/pipermail/wp-docs/attachments/20090708/b8abf8ed/attachment-0001.htm>