[wp-docs] Writing a Plugin

[Owen Winkler]

Michael D.Adams wrote:

>
> Examples are probably appropriate, but I think it would be best to 
> give them their own section.  We really only need a few examples, too: 
> an action, a filter, something that takes one or two parameters (see 
> below).  I suggest we keep the example section _as short as possible_ 
> and encourage people to ask on the list or the discussion page before 
> adding new ones.  I see this article mostly as a quick reference for 
> people, not a tutorial.  (Let me know if I'm being too fascist.)

It should be a referecne, but I doubt "quick" is the word, if only 
because there are dozens of hooks to document.

For many hooks it would be helpful to see the format of data that's 
passed to and from the hook, so each should have an example.  For many, 
like the template tag filters, a "See the X hook for an example" would 
suffice.

More importantly, the action hook locations need to be explained 
thoroughly.  Skippy and I had a discussion on IRC the other day that 
could have been avoided entirely if this was documented properly.  
(Specifically, where edit_form_advanced is inserted.)

> Speaking of keeping things clean, I'd like to eventually get rid of 
> the following sections from [[Plugin API]]:
> #General Guidelines for Plugin Authors
> #Adding Submenus to the Admin Menu
> #Plugin Metadata
>
> and put them on whatever top level Plugin Development article 
> ([[Writing Plugins]], [[Plug in into Plugins]]...).

The content of [[Hacking WordPress]] needs to retitle to [[Writing 
Hacks]].  [[Writing Hacks]] needs to include information on writing 
actual hacks (it currently does) and stuff like the cache plugin 
constant.  A new page [[Writing Plugins]] would contain basic howtos (a 
couple of sections of Carthik's page, but not the whole thing) and links 
to the big sections that don't belong in [[Plugin API]].  [[Hacking 
WordPress]] then becomes an introduction into the methods of altering 
the WordPress code to suit your needs, and a lead-in to the [[Writing 
Hacks]] and [[Writing Plugins]] pages.

We need a big developer function reference, too.  Not just for 
formatting output, either.  There are a lot of useful functions in 
WordPress that could obviate reinventing the wheel.

All of these pages need to fall under a new umbrella from the home page, 
[[Developer Documentation]].  Expect that the rules would be slightly 
different here from the rest of Codex as you delve deeper into it, since 
you're not going to be talking to the average user.  Hopefully, they'll 
realize they're lost and go back to the easily found [[Plugins]], which 
isn't linked on the API page currently, and should be.


> And another thing.  If anyone's been following 
> http://mosquito.wordpress.org/view.php?id=901
> and can tell whether or not this new multiple parameter capability is 
> stable enough to include yet, can you make sure the information gets 
> in to [[Plugin API]]?

That issue is insane.  This needs coverage badly.  It seems to me that 
as far as the API reference is concerned this should be stable.

Owen