[wp-docs] Structure of documentation

[Martin Sturm]

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