Thank you for your quick reply! I will try to explain some of my points:
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:
That's good to hear. As I already mentioned in my previous post, I am willing to help restructure (and improve) the documentation.
> 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.
One example I'm pointing at is the page 'Advanced Topics'. It is a good thing to try to cover a broad range of 'advance' topics on one page, but the problem with this page is that it is a mix of reference pages and tutorials/HowTo's. I noticed this problem on other pages as well. Some links on this page are to pages which aren't 'advanced' at all (such as the 'Wordpress Plugin' link). On the other hand, is there also a link to the plugin API on this page. Another link here is the 'Managing plugins' page, but in fact that is not 'advanced' that is just end-user documentation. It may be better to make a seperate page with 'reference documentation', on which the function reference and Plugin API is listed (amongst other pages), and a seperate page with 'advanced topics' where only tutorials/howto-like pages are linked. Maybe it is not clear for which audience a particular page is written. For example: http://codex.wordpress.org/Writing_a_Plugin and http://codex.wordpress.org/Plugin_API contain a lot information which is on both pages. But they both seems to be mentioned for the same audience and try to achieve the same goal... While I'm looking more careful to the available documentation, the structure isn't as bad as I thought, but is more a navigational problem. It is not obvious where to find the documentation you're looking for. Until today, I didn't noticed the Developer Doc page, because I expected that on that page was information on how to contribute on Wordpress, and not the developers references (which it is). The Documentation Home Page (http://codex.wordpress.org/Main_Page) is another example of a really bad page (and maybe the cause of my problem?). As a 'new' Wordpress user who's looking for some information, this page is just to overwhelming. There are a zillion links on this page, and a lot of them seems to be duplicate or cover the same topic. I think, this page should be a clear starting point and provide guidance where to find particular documentation. For example, take a look at the first four links: 1. Getting Started with WordPress <- ok, clear, if I'm new I have to start here... 2/ New To WordPress - Where to Start <- err.. what's the difference with the previous link? 3. WordPressMU and WordPress.com <- not really relevant I think.. at least not here 4. Installation <- ok, if I want to install Wordpress, I have to look here ... 5. Installation Help <- ... or here? I think it is clear that this is not very 'userfriendly'.
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.
I'm not aware of the history of this page, but according to your reaction, I assume that in the past there was not such a reference. In that case, this is already a big improvement. I understand that one of the problems is missing description of functions, and of course that is not 'easy' to fix (however, if I have some time left, I will try to help to fix this problem).
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.
I have not yet thought of a better categorization of this page, but I will look at it and come with a suggestion if I have one. However, I think it is not optimal at the moment, some categories (especially the 'Miscellanous Functions') are very long. The page would also improve if there is some kind of 'overview' at the beginning. The only way to find a category now is to scroll down the page.
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?
I think a good start is to clean up existing 'overview' pages and think of some kind of structure for the documentation. Currently, it feels like there is not really a structure in the pages.
The central place for plugin development exists: http://codex.wordpress.org/Developer_Documentation
Yes, I didn't notice that page... -- Martin Sturm _______________________________________________ wp-docs mailing list [email protected] http://lists.automattic.com/mailman/listinfo/wp-docs
