Below is a proposal for user-generated content in the code reference.
- Individual code reference pages are split into three sections:
— parsed content
— officially curated content
— user-generated content
Much like this diagram:
- Parsed Content will come from the parser
- Officially curated content will be added by the docs team
- User generated content will be added by users and filtered via voting.
Here are some mockups:
Function page with curated content
Function page with user-contributed note input expanded
Function page with user-contributed note
Full gallery is here:
This will involve two major changes:
- examples will become user-contributed notes. These should be able to deal with both code examples and text
- we will need a way for the official docs to be added. My instincts are that these should be added to the content editing section in the back-end, but at the minute the parsed content is added there. So I’m not sure what the best way to technically implement this is.
I’m definitely open to changes so please make suggestions.
Thanks to @boone for input into this.
The code reference is rumbling along – it’s now possible for people to submit examples, source code can be viewed from pages, and we’re working on upvoting functionality. But before we can embark on the grand codex migration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies., we need to have a way for people to create user-generated content. We’ve discussed this before but made no major progress.
What we want: A simple way for people to add supplementary content and information to the code reference.
How you can help: We need example of how other code references allow users to add explanations and content.
Please respond to this post with examples. Just some screenshots would be great. When we’ve collected a bunch of them we can go through them and see what inspiration we can get for our own reference.
Hey there Docs team. I’ve been working on a turnkey local development environment for Meta sites, and added developer.wordpress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ to it last night.
I think this will be much more convenient for anyone wanting to help out, since they can just install a few programs and then the entire environment will be provisioned for them automatically, rather than having to manually complete the list of setup tasks.
Thanks to everyone who came to the meeting. These were the major discussions:
- Deprecated files – a decision was made by the docs team to not use a deprecated tag in the file header. We need to decide on whether we’re using CPTs for files (if we do we get deprecated for free)
- #176 Source code on individual pages – to be implemented by @coffee2code this week
- @coffee2code confirmed that posts2post can be used on WordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/. @Rarst has opened up a ticket to discuss p2p implementation. The options are to either treat it as a Composer library and require it in the parser. Or to assume p2p is enabled as a plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party and run the parser alongside it. Please provide feedback.
- we discussed settling the theme repository on SVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. and scrapping the repo on Github GitHub is a website that offers online implementation of git repositories that can can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/. In order to do this, we’ll first need to update the devhub instructions to use trac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. tickets and patches rather than GH pull requests.
- still pending: better differentiation on search results pages, explanations in the code reference
I posted this as a comment the other day because i couldnt post here but havent recieved any feedback so im posting it again here now 🙂
Devhub Update 20th May
Here are the designs for the search results pages i have so far:
View – http://developer.compositeuk.co.uk/badges/?s=get_post
Branch (GitHub) – https://github.com/SofiaRose/wporg-developer/tree/feature/Search-Badges
Note: Once theres a way to differentiate between actions and filters the Hooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. Badge (H) will be replaced with a Action Badge (A) and a Filter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. Badge (Fi).
Note: Mobile styles not yet created.
View – http://developer.compositeuk.co.uk/filters/?s=get_post
Branch (GitHub) – https://github.com/SofiaRose/wporg-developer/tree/feature/Search-Filters
Note: Filters still show up when theres no results on search page this will not happen in the next draught.
## Badges & Filters
View – http://developer.compositeuk.co.uk/both/?s=get_post
Branch (GitHub) – https://github.com/SofiaRose/wporg-developer/tree/feature/Badges%26Filters
Which design do you prefer?
In a discussion on skype we thought about making all deprecated badges red, whats everyones thoughts on this?
What are peoples thoughts on hiding deprecated items in the search results and having a show deprecated filter?
If you have another suggestion submit it on meta trac here: https://meta.trac.wordpress.org/ticket/450
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 GitHub is a website that offers online implementation of git repositories that can can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ 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
Thanks to everyone who came along for this week’s devhub meeting. It was a long one! Here’s what happened:
1. Deprecated files – we need feedback from the docs team on this issue. Does it make sense to use deprecated tags at file level? You can find the exact discussion here. @kpdesign can you raise this at the docs meeting – I won’t be able to be there. Please report back in this thread.
2. #176 Source code should display on individual pages. @atimmer and @coffee2code have been working on this. We expect it to land in the next day or two.
3. #79 Used by/Uses – this is partially being parsed but we don’t have storage for it. @Rarst suggested implementing post relationships using Posts2Posts. @coffee2code to check whether this is possible on wp.org
4. Examples – examples are nearly ready to go live. Assigned to @coffee2code to implement. A separate discussion will be had about explanations.
5. #450 Better differentiation required on search results page. @sofia-rose will be posting designs for discussion.
6. We discussed bundled libraries and came to a consensus that they should be included. This means we have to deal with two things:
- grouping and indexing them
- dealing with them in the search results
The second of these ties in with the previous point – better differentiation required on search results page. The search results page needs to show on the one hand, what the thing is (function, method, etc) and also a quality of the thing (deprecated, external, etc). @nicolealleyinteractive is going to put together some mockups for discussion. For reference, this is how deprecated was displayed in Mel’s original designs.
Following this, we did a pass on developer.wordpress.org tickets and closed a bunch of them (yay!)
We did open one ticket: #481. Admins will be able to edit parsed code reference content, but in order to publish they will have to enter the number of the corresponding core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. trac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. ticket to update the docs. This will ensure that we keep track of changes and they get properly parsed.
@DrewAPicture raised the question of the relationship between devhub and core so I’ll use this opportunity to clarify:
- the aim of the devhub project is to produce developer resources for developers working on WordPress (this includes theme and plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party developers, core developers, people building custom sites etc)
- the code reference is one part of that project and is a resource aimed at all WordPress developers
- I (Siobhan) am leading the project with @samuelsidler as my sidekick
- @Rarst is the current lead for WP-Parser. He has extensive experience with building a code reference for WordPress.
- WP-Parser was originally developed for using on developer.wordpress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ but we also want to ensure that it is useful for other developers. Therefore if it has no negative impact on devhub, we are happy to incorporate changes the accommodate other use cases. If that includes parsing information that core doesn’t need and if parsing that data doesn’t have a negative impact on wp.org/ref then we will parse it
- devhub chats happen weekly, we have a tag on trac, and a tag on make/docs. Everything is done in public. No decisions are made behind closed doors. If members of the core team (or anyone else) would like to help steer the project those are the places to get involved. Please do get involved. We would love more participation.
- when it comes to implementation on WordPress.org, we defer to @nacin and @coffee2code
- if anyone from the core team feels that we are missing the mark somehow, please get involved with the project.
In addition to the above, the following needs to be done:
Thanks to all who attended the meeting on Tuesday. Here are our priorities/current issues:
1. Detect deprecated files. Github #11 @Rarst
2. Display source code in code reference – there’s a basic implementation of this from @atimmer 176. Waiting for @coffee2code to review and commit
3. Used by/Uses information Github #79 @Rarst. Once this is being parsed it will need to be displayed #323
- Pending the above we can implement examples #180 @coffee2code
- @nicolealleyinteractivecom and @sofia-rose are working on an implementation for differentiating between different code reference entries on search results page #450. Can you please post your designs here for discussion?
- a discussion needs to be had about skipping bundled libraries. @nacin thinks that bundled libraries should be skipped, @Rarst firmly thinks that they should not be. If anyone has any strong feelings either way, please leave a comment here. We’ll discuss the issue again at the next meeting.
No devhub meeting today. Same time as usual next week.
Good news everyone! Version 1 of the code reference is online. Please note that this is a very early version and there’s still a lot of work to do, but it’s usable and you can take a look at: https://developer.wordpress.org/reference
Please feel free to add tickets to meta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. trac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. if there are any issues you encounter, and if there’s a feature or enhancement you’d like we can discuss that too. We do have the functionality ready for submitting examples, we just need a few parser things fixed before we can deploy Launching code from a local development environment to the production web server, so that it's available to visitors. it.
Thanks to everyone for your hard work so far. It’s really appreciated. Hopefully now that it’s on WordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ we’ll have a flurry of people writing patches 🙂