[wp-docs] Wiki Weekend - Editing Help and Comments

[lorelle at cameraontheroad.com]

Oh, the Codex editing help page and I became best friends and worst enemies 
over the weekend.  I left a note on some "wishes" for modifying it on its 
discussion page, but some issues came up that are "bigger" to discuss since 
they may apply to all of us working on the documentation pages.

ONE
At the bottom of each page is usually a RELATED section of links to topics 
related to the article.  Some tags in the Template Tags were not in their 
right category "stub" listing.  When it was obvious that this was "wrong", I 
changed it to the right "related in same category" by copying the stub from 
a related category that had it right.

But it got me thinking.  How does a, for instance, template tag get into a 
"related category"?  These are generated automatically with a {{tag}}.  And 
not all pages have these, though most do.

I'd love to see "related" items on the Main Page sub pages to help people 
find related informatoin about the topics at hand.  Can we add it there?  Is 
this something the sysop does or can anyone editing do that?  I think that's 
a wonderful feature and I'd love to see it on all the pages, when possible.

----------
TWO
I had a terrible time "faking" links in the visual examples of some of the 
tags and in the Lessons articles I'm working on.

I decided to create a link to the page I was on, so if I was on 
Template_Tags/wp_list_pages then my intra-article faked link would be 
something like

[[Template_Tags/wp_list_pages#Example_1|link text here]]

Instead, it turned the link "bold" without a link reference.  I fought with 
this for hours until I figured out that in the Codex, you can't link to the 
page you are on.  It kills the link.  So I had to find another way of 
creating an example fake link in order for people to "see" the visual 
results of the tag's usage.

Carthik finally helped me by suggesting that I use [[#|link title]] to cause 
a non-action link to the same page.  Didn't work.  The # takes the user to 
the Main Page of the Codex. That's too far a jump for a user to face and 
time wasting to hit the back button.

Since the template tags I was working on all had ==Examples== in the example 
section title, I ended up using [[#Examples|link title]] to cause the user 
who might click on the link example to link to the Examples section - where 
they are already viewing anyway, so it's a minor jump in the page.  Or I 
would use the sub-section title like ===Excluding Categories=== as 
[[#Excluding_Categories|link title]] to keep the "jump" close by.

By removing the actual page title in the link, the link would "work".

We need to add this information (or improve my process) to the Editing Help 
article for intra-article links.

----------------
THREE
When using a DIV to stylize an example, and there is a list inside of the 
example in the Codex, I can't just put

<div style="blah">* Item One
 * Item Two
* Item Three....</div>

The list then looks like this (+=proper bullet and *=asterick symbol - no 
bullet):

* Item One
+ Item Two
+ Item Three....

In other words, in order to SEE the proper bullet and not an asterick, I 
have to order the list with a line break after the DIV:

<div style="blah">
* Item One
* Item Two
* Item Three....</div>

And then it looks right.

+ Item One
+ Item Two
+ Item Three....

Is this a bug or a "supposed to work this way" in the codex?

If you "edit" (screw it up and you'll be shot!) my article 
http://codex.wordpress.org/User:Lorelle/Stepping_Into_Template_Tags in the 
sections where I show off what a category list would be, simply delete the 
line break after a div so it looks like the first example, and then preview, 
you will see the first line item turn into an asterick...at least I hope you 
will.  If not...well, this is just another visit to an auto mechanic and you 
can forget I brought it up.

----------------------
FOUR
This is just a humble opinion style issue, but I'd really like to see a 
little more "space" between the last paragraph of the section above and the 
sub-section title.  In other words, add some padding or a margin to the 
section titles to give them a little more breathing room.  Sometimes it 
feels like they are sitting on top of each other and crowded.  I usually put 
a double space between the section ending paragraph and the next section 
title.  If I'm using a PRE or code box before the section title, it sits 
right on top of the section title.

I'd also like to see a tad more space between OL and UL lists.  Not a 
centimeter or two, but a millimeter or three little bit more space.  If you 
add an extra line space in an OL list, your list numbers are

1. list text
1. list text
1. list text

Just a little thing that has annoyed me since day one.  I like SPACE around 
my writing and examples and trying to force them within the Codex has 
unpleasant effects sometimes.

-------------------
FIVE

No five, but give me a chance.  I'm still processing the stuff I did over 
the weekend....hee hee....got to work on that evil laugh in text.

Lorelle