The intention of the code reference is to replace the current references in the Codex (Functions, Classes, Filters, Actions).
Many of the individual items in these references have a lot more content than simply the information that is provided in the inline docs. Some examples:
Not all of this information is appropriate for the inline docs, however we do want to have it in the code reference.
When we specced out the code reference initially. We planned to allow for two types of user generated:
- examples – generated by code reference users, with up voting functionality to allow the best to rise to the top
- explanations – user generated content that would explain the code reference item, and perhaps go into best practices and use cases (as with the current Codex references).
It’s important to retain this explanatory aspect – WordPress has developers at all skill levels and it’s our responsibility to provide proper education. This will benefit our developer and our users.
The question is “how do we achieve this?”
1. Originally we had planned to use the comment functionality to allow code reference visitors to submit explanations which would then appear in the page:
2. We have the explanatory content on separate pages but linked to on the reference pages (not sure exactly how we would implement this or how it would work).
3. We’re open to any other options. There’s no set way to do this and we just want it to be as useful and easy-to-use as possible.
Here is how a couple of other projects do it:
- php.net has “User Contributed Notes” (scroll down here to see)
- jQuery has explanatory content in the code reference. They host the content on github and then pull it in to the reference. @nacin helped build it so might have some ideas on how we can achieve it without github 🙂
Please do comment with the following:
- examples of other code references you like
- how you think we should approach this content
- ideas about implementation