[wp-hackers] Developer portal

[Jacob Santos]

I will say one thing that PHPdoc is not meant for end users. Yeah, I was 
thinking towards the end that examples would be good and it is nice that 
someone can go back and add them. Furthermore, anyone can create a 
ticket and provide additional documentation wording for files and 
functions. Not the best solution, but it is a possible solution that can 
be done to allow those who are able to create patches to do so. It just 
would be faster for someone to create a patch to get in rather than 
someone creating a patch and then waiting for that to get in.

Really, you have the developer API, which is the PHPdoc, which does 
allow for being as up-to-date with the code changes. Not always, some 
functionality has changed in the past, with additional parameters and 
the phpdoc not being updated or out-of-date, but generally, if the 
person making the patch is paying attention, then the phpdoc should be 
updated as well. The Php.net for the most part is a developer API. One 
with many examples and sometimes combines other functions for great 
benefit, but for the most part just tells you how to use the functions 
and what they are for.

The codex I believe takes a lot of time and is a lot of work. I think 
that is part of the problem, if you are going to spend the hours it 
takes to write an article, then I think most people would rather do it 
on their own web site so that they can get the traffic. In the past, 
from what I've seen some have been wrong, incomplete, and become 
outdated. There have been many times that I wanted to take a post and 
update it, but there is the whole copyright issue and I didn't feel like 
rewriting a lot of what was already good content.

Well, PHP.net uses DocBook, so there isn't any reason why it couldn't be 
like the Codex. The contributors and the maintainers probably just wish 
to have it that way so that they don't spend all of their time writing 
every possible usage case for functions. People should discover other 
ways to use functions on their own and with time they usually do. Same 
way with WordPress. Most of the functions aren't often used together to 
create an component. Most could use a few examples and be done with 
them. The examples could even be part of the phpdoc, but I caution doing 
so because it requires special styling to be pretty and that isn't easy.

The problem has been and will always be finding contributors to creating 
these examples. Mostly I think it is a good idea to have a tutorial 
collection section so that people can get external sources to solutions. 
Some people have very good tutorials that beat out anything that is on 
the Codex and it is better I think to give them some link love. The 
point should be education and while it isn't central to where anyone can 
immediately find what they are looking for, the incentive for writing 
something is there and I think that is what matters. If someone wanted 
to ask for permission to put in the WordPress DocBook project and, or 
the Codex, then that would be good as well.

More people might be willing to put tutorials and information on their 
own sites than the Codex. I don't think asking people, and I don't think 
you are personally, to give up their time is productive. People have a 
number of reasons to contribute, but when you increase that incentive or 
provide an incentive you increase the odds that people will do so.

Oh yeah, my point actually was that there should be both the Codex / 
DocBook and the PHPdoc and that they should complement each other.

Jacob Santos

Jeremy Clarke wrote:
> 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 :)
>
>