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 _______________________________________________ wp-docs mailing list [email protected] http://lists.automattic.com/mailman/listinfo/wp-docs
