[wp-hackers] Developer portal

Tue Dec 15 04:53:34 UTC 2009

Here are some thoughts: We had a simple modification of a WordPress site were we could have a tutorial and/or the basic documentation for a function or a concept and then in the comments people in the community could add their suggestions and even include a summary along with related articles. 

The users could select a comment type and one of the types could be link to a related article along with appropriate fields.  Users could also give thumbs up or thumbs down for being helpful, and if the vote goes negative those would be hidden. The comments could also be displayed in descending vote order with newer comments given a month at the top (unless voted negative.)

A process could also test links periodically and mark the bad links.

Periodically the keepers of the content could revise the main article and incorporate the better comments including an acknowledgement of the person who made the contribution and a link to their article.

This approach would provide great content, community involvement, and individual incentives for contributing.

-Mike

On Dec 14, 2009, at 10:07 PM, Jacob Santos wrote:

> 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 :)
>> 
>>  
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers