Tag Archives: feedback

Your feedback on the WP REST API

Earlier today, I tweeted:

Right about now seems like a good time to get official feedback on WP REST API from @wordpress’s lead developers and committers. Just sayin’

Helen, a lead WordPress developer, replied with:

Where does this feedback go, how is it structured, what makes it “official”, and how binding is anything that is said?

To which I replied:

maybe: 1) make/core or personal blog posts 2) I have suggestions 3) comes from your voice 4) actual goal: build consensus

There’s a lot of background to this exchange. If it doesn’t make sense to you, first read this WP Tavern post and then read this Post Status post. The tldr: we’re at a juncture for the WP REST API (a good thing!) where we’ve completed a ton of work (four years for Ryan, in fact) and need to make decisions on whether it’s ready to be merged, or needs additional work before merge consideration.

And we need to make these decisions as a group. Of individuals. With very different: backgrounds, opinions, experience levels with the REST API, and experience levels with other APIs. I’m sure you all know how group decision making goes.

Before we make decisions though, it would be incredibly helpful to have as much information on the table as possible — so everyone can know all sides of the decisions we need to make. This is why I publicly requested “official” feedback on the WP REST API from the WordPress project’s lead and contributing developers:

2016-02-09 at 5.17 PM.png

 

The feedback doesn’t need to be of any particular form. Jeremy Felt already posted his, which is A+, very much appreciate. And, we (Ryan, Rachel, Joe and I) would love constructive feedback from anyone and everyone — but WordPress’ lead developers and committers are the ones who will be maintaining this project for the long term.

If you’re looking for inspiration on how to get started, I typically try to frame my feedback as:

  • What I like.
  • What I’d like to see improved.

Both of these could cover:

  • What you like about the features the REST API supports, and which features you think are a priority to add before merge (and after).
  • Of our documentation, what topics you find explained well, and which should we focus our efforts to improve upon.
  • Of our codebase, what abstractions and patterns you find delightful, and which you think are confusing.
  • What you like about how we’ve conducted the project so far, and what changes you think we need make for the next six months to be successful, and the twelve months after that.

Ultimately, “should we merge it?” is a binary decision. But, getting as many perspectives as possible out in the open will help us better explore the potential ramifications of the decision, which is more important than the decision itself.

If you don’t want to post on your personal blog, then leaving a comment on this post is a great place for your feedback. Thanks in advance!

Feedback for Harvest’s Forecast

I love, love, love Harvest. As a solo shop, Harvest is a $12/month investment which feels like a $400/month return.

One workflow aspect I’d love Harvest to solve for me is time forecasting. Here’s how I currently keep track of my commitments in iCal:

2016-02-09 at 7.46 AM

These details are a pain to keep updated, and rarely accurate. I’d love for Harvest to feed this data into my calendar automatically — project name, allocated hours for the week, actual hours to date.

Fortunately, Harvest has a secondary application called Forecast for team scheduling. Unfortunately, I ran into a couple of annoyances that will probably turn out to be blockers:

  • Forecast doesn’t automatically integrate with Harvest, where I’ve already identified my projects (and time budgets associated with each).
  • Given I jump between projects a bit, I’d like to be able to budget my time on a weekly basis instead of an hourly basis (e.g. 8 hours/week for a given project).

I can understand the appeal of producing Forecast as a separate product, but I really think Forecasting makes most sense as a feature of Harvest.

I’ve submitted this feedback to Harvest via support ticket, but thought it would be fun to blog too!

The pain of customizing WordPress themes

2015-12-15 at 9.06 AM

Choosing a WordPress theme from the Customizer is a bit painful.

First of all, “Search installed themes” doesn’t make sense as a string on a hosted WordPress service. As a user, I have no ability to install new themes. It could be edited to just “Search themes”

Second, as a user with a blog, I want to choose from themes that showcase my words. The first suggested theme appears to be a product portfolio, and the second suggested theme is for a restaurant website. I should be able to indicate I just want to see writing themes.

Third, the “371” indicator next to the “Customizing Themes” heading has no meaning whatsovever. 371 what? Is that power user UI?

Some unsolicited feedback for the Fields project from my time with the REST API project

Capturing advice I left for the sands of time.

  1. Set a clear mission statement for the project. This will give clarity to the problem you’re solving, what to say yes to, and what to say no to. You ideally want to avoid crises of faith late in the project.
  2. For your contributors, clarify involvement expectations. When most contributors are doing so in their “free” time (e.g. not getting paid directly for it), it’s really difficult to budget for unlimited development scope. A little bit of proper project management goes a long way. I feel like WP-API is a much more sustainable project with four contributing developers than two. I would encourage you to have at least three.
  3. Model your data before writing code. What is a field? What attributes should it have and why? What is a control? What attributes should it have and why? When you dive into development before appropriately modeling your application, you run into these implementation details one by one, and burn a lot of time (waiting to) discuss them.
  4. Focus on clearing blockers above all else. Because you’re working on an open source project with contributors across many timezones, average time to feedback will optimistically be 6 hours. More likely, it will be 24-48 hours. This slow feedback cycle can kill progress on pull requests. As a project maintainer, prioritize giving feedback, clearing blockers, and making decisions.

Thoughts on using WP-API for WordPress-based apps

This past week, I got to do my first client project using WP-API. The scope of the project is to create custom endpoints for a WordPress-based web application. The endpoints will eventually be used to power iOS and Android apps.

I thought I’d use the opportunity to gauge usability of using it in a project. My feedback is from the perspective of a developer needing to create custom endpoints for WordPress — I haven’t written any client-facing code yet.

These notes are roughly edited. Mostly I just want to get them up before WCSF.

What I like

WP-API has a comfortable implementation of using WP_Error for returning error responses in my endpoint callbacks. Being able to specify the HTTP status code is a great touch.

Extending WP-API’s core classes is really nice for DRY. They should be designed to be extended — I’d suggest they’ll be more commonly extended than used standalone.

For instance, I was able to get a lot of mileage out of extending WP_JSON_CustomPostType and customizing the response values for prepare_post(). However, I basically reset the original array (because the project has different data models), so it would be cool if there was some reusability there.

Also, I was able to easily add an authentication check for get_posts(). But, I wasn’t able bypass delete_post()’s capability check, so I needed to create my own.

Context argument is proving to be easily reusable. I invented my own context that seemed to fit in the paradigm.

Route registry is pretty much copy and paste == it works. I love the style of route definition too: /(?P<id>d+)

What can be improved

Using bitmask operators to map HTTP methods to callback isn’t terribly intuitive, although it’s easy enough to get going by copy and paste. I’ve never liked that part of the Rewrite API, and don’t think we should repeat it.

It would be nice to be able to modify the “data” field associated with a WP_Error entry. I’ve set up my models to return WP_Errors, but then I need to recreate that error in my controller to include the status code.

Because we have a variety of content models that are often mixed and mashed (e.g. a Post displayed with Author, Terms, and “Featured Image” Attachment), we should do embedded media really well. I think this is lacking in WP-API right now — you basically need to reinvent the wheel on each endpoint.

I’ve spent way too much time writing code to define and validate supplied arguments. I know this is something I like and Ryan hates, but it would be cool if we could nail field definition and validation for endpoints. This is something we did with H-API. It seems like we’re part of the way there by using Reflection for argument definition in our endpoint callbacks. Easy type validation is just the next step — maybe it could be introduced as an optional library.

On that note too, using Reflection against the defined method arguments to decide which request arguments are passed is too magical. It’s new to PHP and will be completely baffling to Joe Shmo WordPress developer.

Appropriate mediums for appropriate conversations

The administration of Whitman College, the school I went to for my freshman year, has decided to cut funding to its Varsity Alpine and Nordic ski teams. The community is in uproar about this decision; if you aren’t on one of the teams, then you have a friend who is. Andrew Spittle, the Web Manager at the Whitman Pioneer, saw the controversy as an excellent time to experiment with their new website. In a post published on the CoPress Blog today, he goes into detail about the different tools they used to get the word out (Twitter, list serv, Facebook, and banner ads), and reveals how effective each medium was for driving traffic to their stories.

Twitter wasn’t effective at all, as it only sent less than 1% of their overall numbers. In the comments, I mention that his assessment is almost there. Twitter is a really valuable tool, but that value only applies if you can reach your community on it. The Whitman campus isn’t there yet in terms of adoption, and might never be, but there is the possibility that it will become more effective for discussion in the near future. The Pioneer leading the charge, pardon the pun, by actively advertising discussion like this might be one way to increase the number of users, or that number might grow once the campus learns the value of Twitter via SMS for finding the best parties on Friday night. I wouldn’t discount entirely, it’s just a matter of engaging in conversation where your community is.

Continue reading “Appropriate mediums for appropriate conversations”

Free strategic advice for the @dailyemerald

Last night, I realized we’ve started bitching about the Daily Emerald in the peanut gallery without offering any positive advice for change. I’d like to offer my thoughts on how to turn the struggling newspaper into a successful digital news enterprise.

Step one: hold a transparent weekend (or weeklong) jam session to develop a strategic plan. Invite as many intelligent stakeholders as you can to a retreat, and put together a website for that retreat with the agenda, list of everyone involved, and goals. It might also be useful to have a open community forum in the week preceding to hear strengths and weaknesses from the perspective of the audience, or launch a website where the community and submit and vote on ideas for the news organization. When retreat happens, however, make it open and participatory. Make sure everyone at the retreat is documenting the discussion on Twitter, and livestream as much of the discussion as you can. Have a designated “community manager” for the retreat who looks for suggestions from watchers and brings those to the meeting. Tap the intelligence of the digital crowd, especially because you’ll be able to bring even more smart brains from afar.

Step two: campaign over summer 2009 amongst the Daily Emerald alums to raise the funds necessary to implement the strategic plan. Shop the plan out to them to get their feedback and insights, and use CRM (or customer relationship management) software to track these interactions. When I left, they were using a FileMaker database system and analog mail. I would ditch this system immediately, and my first investment would be software like Salesforce.com (which a news organization could also use to sell advertising more effectively). Using the new CRM, it would be wise to fundraise amongst the alums who want to see their old newspaper experiment with this platform called the internet. Including them in the process, by sending them the strategic plan and a link to the website with an archive of all the video, will make them more invested in the process (if they like what you’re doing at least).

Step three: implement the strategic plan starting in Fall 2009. If I were the publisher of the Daily Emerald, these three are of many things I would attempt to drastically right the direction of the news organization:

  • Quit the College Publisher habit. Being on a locked, proprietary content management system is probably the worst foundation you could have for a digital news organization. Focus heavily on recruiting a few developers out of the computer science program, and build a basic website on Django that you can grow from. If you ask nicely, the Daily Gazette at Swarthmore or Daily UW might be willing to lend enough code to get you started.
  • Move to once a week in print. I know that this would be very, very difficult, especially because the bulk of revenue comes from the print product, but it needs to happen nevertheless. Necessity is the mother of invention. Do it, and publish daily online.
  • Empower your community. Break down the ivory tower, and hold workshops to teach interested community members how to report on the issues they’re passionate about. I am quite certain that club sports at the University of Oregon don’t get the coverage they deserves, and there are probably at least several people who could tweet at games and submit high quality images for a photo gallery.

Right now at the Daily Emerald, though, they’re going about it the API emergency meeting way, and this is just one of the many reasons I think startups make more sense in this climate. I mean, look at all of the effort it’s going to take to turn this ship around, let alone reinvent it.

There’s also been discussion that student news will be largely unaffected by the tornado ripping through regional newspapers right now. Even if that is the case, I would like to propose an analogy: if you’re driving towards the cliff of irrelevance, your direction is what is most important. It doesn’t matter that your car’s engine hasn’t seized up yet.