[wp-docs] Structure of documentation

[Jennifer Hodgdon]

Martin Sturm wrote:

> I have to say that the documentation on Wordpress is very complete and
> covers almost everything, which (I think) is a very good thing.
> However, I think there is a rather big problem with the Wordpress
> documentation, and that is its structure. It is very hard to find the
> thing you're looking for. Especially when writing plugins I notice
> this problem.

Hi Martin,

You have made some good points, and I have actually been working on 
cleaning up the developer documentation along many of the same lines, 
but there is more to do. In answer to your specific points:

> 1) Tutorials, howto's and reference documentation seems to be mixed
> togheter. While tutorials and howto's can be useful in some cases,
> they are distractive when you're looking for one particular function
> or method.

Can you be more specific? I have been trying to make this separation 
on pages that I have edited, but if you have specific suggestions for 
pages that need to be broken up, that would be good.

> 2) The function reference (which is not easy to find, I only noticed
> it after a while) is not structured very well. [and most of the functions are not documented...]

It is definitely true that more of the functions need to be 
documented... but at least they are all listed now. The problem is 
that someone still needs to write about a zillion individual function 
pages, or at least add short descriptions to the functions. Feel free 
to jump in and write them. There is a standard structure for function 
documentation, so if you write a function reference page, start by 
copying an existing function doc page and go from there.

Also, can you suggest better categories? I would be happy to 
reorganize the list, and definitely functions can be listed in more 
than one section. For my first pass at getting all the functions at 
least listed, I just used the categories that were there previously. 
But there is no reason that it cannot be made better.

What other navigation features do you think would be good? You 
mentioned php.net as a good example -- what navigation features does 
it have that we should try to emulate, given that we are working 
within the WordPress Codex, which contains documentation for everyone 
from casual users to hard-core developers?

> 3) The plugin API is documented very badly. With this, I'm referring
> to the documentation on the action/filterhooks. This page is just a
> long list, where a large number of the hooks isn't documented at all.

Again, someone needs to document them. Each one should have at least a 
  short description, but someone needs to write these descriptions. 
Please feel free to jump in...

>  Additionally, a central page for plugin
> development should be created. This page should containg links to a
> clear function reference and actions/filter-hook reference. 

The central place for plugin development exists:

http://codex.wordpress.org/Developer_Documentation

Thanks for your input!
      Jennifer

-- 
Jennifer Hodgdon

Poplar ProductivityWare * www.poplarware.com
Web Databases/Scripts * Modeling/Analysis/Palm OS Software