[wp-hackers] Developer portal

[Jeremy Clarke]

I think the best function documentation is and should be the source
itself. When the PHPDoc descriptions are well done they are incredibly
useful, especially for people who use IDEs like NetBeans or Eclipse,
where the result is that you have the docs in your face as you write
your code (seriously guys, if you tried WP in an IDE before version
2.5 or so you should try it again, the value of autocomplete
skyrocketed with the addition of PHPDoc)

Whatever the solution for the function docs ends up being it should be
based on the phpdoc inside WP, at least for the core descriptions,
which can be up to several lines long and in many cases are all you
are likely to need when coding. Using PHPDoc also means that even if
this new reference gets old and dies the docs are still there and
tools like PHPXref will continue to derive intense utility from their
presence.

For longer descriptions and examples I think php.net is a clear winner
in terms of how to organize it. Offer at least one example for each
function and have a space for comments, along with a rating system
that votes comments up if they are useful. Stack Overflow is also
probably a good source of inspiration for the comments. If we thought
of the 'comments' as 'tips' or something and treated them as each
their own thing then a voting system would be really useful for
effectively defining best practices and having them show at the top.
If there was a manager of this thing they could also obviously
incorporate the best 'tips' into the core document itself. Maybe each
top-level comment is a 'tip', while sub-comments are comments on the
tip.

If the function reference doesn't inherently involve an Xref style
linking structure that explains where functions are used in core and
links back and forth to definitions then it should also include links
to a PHPxref install. I.e. on each function you'd have a link "See
this function defined in Xref" and "See uses of this function in WP
Core Xref" that link to the right places on Westi's phpxref
(preferably after migrating it to wordpress.org)

Ideally the solution would also simplify the process of helping to add
to the PHPdocs inside WP. Keeping all community documentation effort
inside the code itself is the best way to ensure that nothing is
duplicated and everything is kept up to date (after all, its easier to
double-check the actual function definition in the code when you edit
a function then to search the whole internet for code examples you've
deprecated).

IMHO it is currently too hard to help with the PHPDoc effort. While
for some of us using trunk SVN, exporting diffs, and using Trac feel
natural I think we can all agree that it is a specialized system and
is in no way obvious or friendly to people who just want to help with
documenting their favorite functions. Updating/adding a phpdoc should
only take a few minutes, and doesn't need to involved  learning the
byzantine ways of WP Core Development.

It seems to me that a submission process that removes all that cruft
would be very much worth it. Something like a button on the function
reference that says 'suggest a better phpdoc for this function'. The
user could then write a better doc and submit. At that point it could
be emailed to a core developer in charge of PHPDoc. For that core
developer turning the doc into a patch and committing would take like
2 minutes, be very unlikely to cause problems, and wouldn't involve a
long trac issue explaining it. They'd probably want to double-check
that the docs are accurate, but they have to do that anyway right now.
IMHO taking some text, incorporating it into their local working copy,
and committing it would probably take *less* time for a core dev than
dealing with a trac ticket and patch, as well as making it like 90%
faster for the submitter. I know I would use this tool even though I
know how to make patches and use trac.

In terms of best practice documents I've found that the most useful
docs are the ones that cover a whole API explicitly and
authoritatively. Codex articles like Widgets API, Shortcodes API etc
are very useful and provide a perfect place for wikipedia style
'external links' to articles that explain it in more personal terms.
In this new portal I think the function descriptions should be atomic
and anything else should be abstracted into some API that can have a
holistic page about its use. This way there are only two kinds of
pages, which IMHO will help with the redundancy experienced in the
codex. Each function doc should also link to any relevant APIs, which
wouldn't be too hard to do by just going through the (hopefully
relatively short) list of API articles and adding all that apply to
the function. If its actually based on WP then each API could even be
a category, and you could just check the categories appropriate for
each function (I think I just blew my own mind).

One last thing: There will need a paid Automattic employee who knows
how to code and is in charge of maintenance and updating things based
on user feedback. I hate to give up on the community does everything
model, but unless someone is personally responsible for this it will,
eventually, rot and crumble like the wiki.

Apologies for the incredibly long reply to an already long thread,
hope everyone is having a good Sunday :)

-- 
Jeremy Clarke | http://jeremyclarke.org
Code and Design | http://globalvoicesonline.org