User:CharlesClarkson « WordPress Codex

1 Me
2 Summary Box
3 My Codex Bookmarks
4 Individual Function Reference Pages
5 Scratch Pad
- 5.1 %
6 Go For It

Me

Hi. My name is Charles K. Clarkson. I am a web programmer, real estate investor and free market advocate (not necessarily in that order.) I enjoy reading, music, cooking, eating and sleeping.

My Home page

-- Charles Clarkson 13:28, 27 November 2008 (UTC)

Summary Box

--CharlesClarkson 04:19, 9 December 2008 (UTC)
Summary Box Edit Grrr. I've been using the Summary box all wrong. I'm so embarrassed. Apparently, not everything is to go between the /* */ tags. Apologies to all those editors checking my edits.

As a good programmer one would think I would have read the manual first. Perhaps I'm not as good as I think I am.

No, wait. That couldn't be it.

My Codex Bookmarks

Links to Pages I need often.

Individual Function Reference Pages

CharlesClarkson 11:33, 9 December 2008 (UTC)

Introduction

Last month I broached the subject of editing the Individual Function Reference Pages on the WordPress Documentation mailing list. I was concerned that just jumping in without any direction would be counter productive and I was afraid that my very little experience with editing this particular wiki might lead to me doing a lot of work without much benefit to Codex readers.

I didn't get a lot of feedback and I'm still a bit frightened to get started. To avoid getting started I have been rereading the Codex Guidelines and correcting smaller mistakes in the Codex to gain some experience and confidence.

The mailing list members seemed to think I should just jump into the deep end of the pool, so I guess it's time to take a leap of faith. I'll save the high dive for later.

Here's my introduction for editors and page creators for Individual Function Reference Pages.

General Editing Guidelines

Thanks for your interest in editing or creating a function reference page. No one expects one author to do all the work to complete each page. We want many different contributors editing each page. This is especially true of the Examples section. Feel free to add whatever you can.

Here are some things to keep in mind while editing:

Assume the reader is using the latest stable WordPress version.
- Avoid section headings with a WordPress version in it.
- Use the Change Log section to specify version specific changes.
Assume you are speaking to a beginner PHP programmer, not a seasoned professional and not an idiot.
Don't write about yourself. Write about the function and its benefits to the reader.
Avoid jargon. Some jargon cannot be avoided when writer a technical reference, but be careful.
- Assume your reader only knows:
  - HTML,
  - xhtml,
  - CSS,
  - Most PHP functions, concepts, loops, etc.,
  - MySQL,
  - variable,
  - object
- Do not assume your reader knows what MVC, OOP, sorting algorithms, linked lists, singleton or more advanced programming concepts mean.
- Many PHP specific concepts are already explained in the on-line PHP manual. Feel free to link to specific pages in that reference.
- If you have a difficult or complicated concept to get across, add it in the Glossary and point to it in a link from the function page.

Function Page Outline

This looks daunting, but documentation about documentation looks a lot longer than much of the documentation actually is. If it is just too much information for you, just select one section in the page and work on it. Assume someone else will finish it up later.

Here is just the bare outline without the details:

== Description ==
== Usage ==
== Examples ==
== Parameters ==
== Return Values ==
== Notes ==
== Change Log ==
== Source File ==
== Related ==

== Description ==
A good description of what this function does. Think paragraph rather than a single sentence. Explain why the reader might want to use this function.

== Usage ==
%%%<?php usage goes here ?>%%%
%%%<?php usage goes here ?>%%%
%%%<?php usage goes here ?>%%%

== Examples ==

=== Example Name ===
<pre><nowiki>
// Example code
</nowiki></pre>

=== Example Name ===
<pre><nowiki>
// Example code
</nowiki></pre>

Etc.

== Parameters ==
This function does not accept parameters.

- or -

PHP data types:

array
boolean
double
float (Rarely used. PHP usually returns double for float.)
integer
NULL
object
resource
string
unknown (or 'unknown type')

== Return Values ==

This function does not return a value.

- or -

Use a dictionary list to specify the value name and description.

; value : description.

If the function returns an object just state that and we will add a description of the object later. Don't try to add an object description it on this page.

== Notes ==
This is a good place for:

Any other actions this function may perform.
Any external variables or object which this function changes.
Anything that just doesn't seem to fit in one of the other sections.

== Change Log ==
Describe recent changes in this function's use. Include the WordPress version number if known.

Recent deprecated parameters;
Recent version changes;
Recent database changes;
Recent philosophical changes;
etc.

== Source File ==
Which source file defines this function.

== Related ==
Links to related functions, codex pages and other useful stuff.

Scratch Pad

Ignore this section: This is a space for me to play with codex styles and tags.

fopen()

%

3 - fixed font

Go For It

Charles, you have our permission, though you don't need it, to run forth with glory and joy. I've made a note on Raimy's pages about the various Conditional Tags started that you are going to finish those. Please let me know when they are ready to review and I will move them from the user pages to the Codex proper. If you have any problems, let me know directly or through the mailing list, or in the #wordpress-docs IRC, which I'm trying to hang out in though I've been out more than in lately. :D

Let me know how I can help you in any way. You are wonderful and much appreciated!

Lorelle 06:06, 12 December 2008 (UTC)

Codex