Content in the Code Reference

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.

#devhub

Help research content creation workflows for the code reference

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, 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.

#devhub

Hey there Docs team I’ve been working on…

Hey there Docs team. I’ve been working on a turnkey local development environment for Meta sites, and added developer.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.

#devhub

Devhub update 1st June

IRC Logs
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. @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 and run the parser alongside it. Please provide feedback.
  • we discussed settling the theme repository on SVN and scrapping the repo on Github. In order to do this, we’ll first need to update the devhub instructions to use trac tickets and patches rather than GH pull requests.
  • still pending: better differentiation on search results pages, explanations in the code reference

#devhub

Devhub Search Results Badges

Hi All,

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:

## Badges
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 Badge (H) will be replaced with a Action Badge (A) and a Filter Badge (Fi).
Note: Mobile styles not yet created.

## Filters
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

Sofia xXx

#devhub

Explanations in the Code Reference

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:

Please do comment with the following:

  • examples of other code references you like
  • how you think we should approach this content
  • ideas about implementation

#devhub

Devhub Update 20th May

IRC Logs

Thanks to everyone who came along for this week’s devhub meeting. It was a long one! Here’s what happened:

Current Priorities

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 trac ticket to update the docs. This will ensure that we keep track of changes and they get properly parsed.

Devhub organisation

@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 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 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.

Further tasks

In addition to the above, the following needs to be done:

#devhub

Devhub update

IRC Logs

priorities
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

Other issues

  • 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.

#devhub

No devhub meeting today Same time as usual…

No devhub meeting today. Same time as usual next week.

#devhub

Good news everyone Version 1 of the code…

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 trac 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 it.

Thanks to everyone for your hard work so far. It’s really appreciated. Hopefully now that it’s on WordPress.org we’ll have a flurry of people writing patches 🙂

#devhub