[wp-docs] Structure of documentation
yahgrp at poplarware.com
Wed Feb 21 14:48:32 GMT 2007
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.
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:
Thanks for your input!
Poplar ProductivityWare * www.poplarware.com
Web Databases/Scripts * Modeling/Analysis/Palm OS Software
More information about the wp-docs