[wp-hackers] Inline documentation

[Matt Mullenweg]

Robert Deaton wrote:
> -1, the codex is far too unreliable as far as I'm concerned, half the
> time its timing out, nowadays its been giving random 500 errors, the
> rest of the time its terribly slow. On being less readable, I think it
> has the advantage of being easier to read than shifting through all
> kinds of useless stuff for developers that's located on the codex,
> since it is geared more toward the end users than those developing the
> source.

That's really a separate issue. It doesn't need to be the Codex, it 
could be any user-editable rich HTML interface.

If the goal is making things more accessible for new developers, than we 
would be stupid to not have a human readable, searchable, and thorough 
online version.

I don't think we should auto-generate developer documentation for the 
same reasons we don't auto-generate the UI:

http://daringfireball.net/2004/04/spray_on_usability

If the goal is just to get javadoc-formatted style cruft in front of 
every function in WordPress, let's state that directly. I think there is 
a very small percentage of users who intuitively grasp javadoc, and 
while they're loud I highly doubt there's an overlap with the audience 
we're trying to address. It doesn't educate anybody,

-- 
Matt Mullenweg
  http://photomatt.net | http://wordpress.org
http://automattic.com | http://akismet.com