[wp-docs] Structure of documentation

[Martin Sturm]

Hi everybody,

I'm new on this list, but has something I want to share with you.

I'm using Wordpress for about three years now, but decided last few
weeks to modify my weblog in various ways. I wrote some plugins and
themes in the past, but now I had to write some more advanced plugins
and a completely new theme. Because I wanted to do this 'the right
way', I decided to read the documentation on these subjects carefully.

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.

I have thought about this problem, and what's the cause of it. I think
there are several problems causing this rather chaotic structure.
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.
2) The function reference (which is not easy to find, I only noticed
it after a while) is not structured very well. Currently, the
functions, options, classes are sorted by a (seemingly) random
categorization, which is not very obvious to understand (in my
opinion). For example, it took me some time to discover that the
databaseclass  was actual part of the function reference (its location
is not obvious). Another problem with the function reference is that
it is hard to navigate. A better navigation structure (in my opinion)
can be found at the function reference at php.net. It is easy to
navigate, the pages for individual functions are all structured the
same and you know where you have to look for a particular function.
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.
I think this is one of the most important parts of the developer
documentation of Wordpress. Good documentation on how to write plugins
is essential to lower the barrier for new developers.

I'm aware of the fact that Wordpress is an open source project and
that documentation is traditionally a difficult part of open source
projects. However, I think that Wordpress is doing very good on this
point and that the documentation is very complete. But I think that if
the structure of the documentation is improved, it can be a lot more
usable and make plugin and theme development easier.

The most important thing is seperate how-to's and tutorials from the
reference documentation. 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
current page on plugin development is good, but more a tutorial. A
link to this page can be added as well (of course). The reference
documentation should be structured better, function reference should
follow a strict pattern.

Of course, I'm willing to help improve the documentation of Wordpress,
because I'm using it rather intensively and like the 'simplicity' of
it (creating plugins and themes is very easy to do).

--
Martin Sturm