Great expectations: Prepare your non-developers for a REST API project

This is a transcript of the talk I gave at  A Day of REST Boston 2017. It’s a short version of my talk The WordPress REST API: A Guide for Non-Developers presented at WordCamp US 2016. You can watch the video from that on WordPress.tv.

Great expectations: Prepare your non-developers for a REST API project – slides and transcript

Today is all about learning how far you can go with the REST API. All the amazing opportunities it provides. All the paths to get to building the projects of the future on WordPress. It’s a much-needed breath of fresh air for our favorite cms.

Our favorite cms that is trying to solve too many problems on its own and ending up failing at quite a bit of the tasks – performance, security, scale…

If WordPress was a creature it would be at the verge of breaking down, because of the impossible expectations towards it to be good at EVERYTHING and do everything itself.

It’s exhausting to want everything from a single platform.

So it’s the REST API to the rescue. The REST API will help WordPress learn to delegate. With the help of the REST API, WordPress will be able to focus on what it does best – providing amazing space for authors and editors to create content. The REST API will help WordPress to finally stop worrying about the front end and let the cool kids developers love playing with deal with it.

But as any growth process, there are some growth pains that we need to be aware of when you decide to build projects with the REST API.

With the decoupling of the front end and back end of WordPress, the features allowing you to customise the way your site looks will be lost, unless special efforts are made towards re-building them.

The “Appearance” settings – menus, background, the editor, the customiser plus the previews of posts – the link between the front and backend, need to be specifically built within a REST API theme to be available.

That, as you might imagine, could be a problem for a lot of people who are used to building a website with WordPress using just themes, plugins and implementing a bit of code here and there.

The major difference between building a WordPress project and a custom project is that the chance of your PM or client to already have expectations on what they can do with their future site are about 100%.

They will have certain expectations about how the editor will work, about their abilities to tweak things, preview things, manage menus, create and modify layouts. The great thing about WordPress is that even if you’re not a developer you have the ability to create a site from scratch. And maybe a lot of them will have.

So you might have seen Siobhan and myself run around this morning and during lunch time. We’re a part of your A Day of REST organizing team. We both have been involved with WordPress for quite a while and know more than how to just create content. Siobhan’s been using it for years, taking advantage of all the opportunities it provided and playing around themes and plugins. I came to IT from marketing and public relations, spent 5 years as a project manager in a publishing companies, telling developers what to do without any idea of how on earth they’d do it. But for me discovering WordPress in 2011 was mind blowing because I no longer needed you lot. I did not need a developer to build a website anymore. Until this happened :)

This story illustrates what happens when you don’t prepare your non development team for a rest api project and second, and more important, this is me giving feedback to the developers of the project, who also happen to be my bosses, about the project.

Back to site builders. Those people building WP sites with no code. Siobhan and I are site builders. The Do it yourself kind, that besides creating content, were also used to using and tweaking themes. So when the time came to organise A Day of REST, which was our responsibility, we had to decide how to organise the website.

At that time, the development team at Human Made was super busy and we had to find a fast solution to put the site up so we could announce the conference.

When we created the first website for A Day of REST London, we decided to go with a theme to save time and resources. So in a way, we took advantage of everything the WordPress ecosystem had to offer – WordPress core, a premium events theme, our own knowledge of how to tweak it to fit our corporate identity. In less than 2 days we had a site. But it wasn’t great. And not only it was not great, it wasn’t ideal for a conference dedicated to the REST API to not use the technology for its own website. There were people on Twitter yapping about things that were not obvious and I could not understand related to performance and usability but I decided that if our dev team suddenly decided that their arguments were valid, then that was a justification enough to build the site with a react theme. For me, that meant that Twitter would shut up and I’ll be able to go on and happily continue marketing my event. Little did I know…

So Joe rebuilt the website in a weekend, using the REST API and a React power theme designed by Noel. He also opensourced the code and created a cute little widget at the bottom of each page that allowed developers to see the API requests for each of the pages. They quickly launched the site reusing the content we already had in the old one. Brilliant!

To make his point and share the experience, Joe wrote a post explaining why he rebuilt the theme, how he did it, how we’re open sourcing it so everyone can watch and learn (yay) and also – what’s missing from the site in terms of functionality compared to a normal WordPress site.

And it is in this post exactly that Siobhan and I found out about the impact the change would have on our publishing and site management processes.

Overnight, we ended up unable to preview posts, manipulate images within posts, create and edit menus and do any type of CSS tweaks. Needless to say we couldn’t add plugins but the most impactful thing were the limitations that were introduced when managing content. Even the smallest changes needed a developer with enough JavaScript/REST API knowledge. We waited days to get a new menu item added, or to add the sponsor logos to the front page, we couldn’t insert links in pages that were not built using the modular page builder on the backend.

So even something as simple as adding a link to a page became a problem.

I don’t need to mention how the control freak, do it yourself wannabe inside of me was feeling. For years I’ve always been able to figure something out when it came to using WordPress. This time, my hands were tight. I was back to this sorry miserable 2007 state where any change on my website needed a developer.

Siobhan, as an accomplished, published author, was more eloquent. In a WordPress company consisting of 90% developers, we were involuntary victims of the miscommunication about what the cool new theme would take away from us.

So going back to that particular challenge – a sound advice – be sure to prepare detailed specifications for your clients when proposing a REST API project. Or make sure they know what they are asking for when they ask you to build them a project with it. Don’t let them believe that just because it’s WordPress, it’s going to have all the core features. Be aware of the decoupling of the front and backend. Talk to your non developers about it. Otherwise they’ll end up trolling you from all sorts of different stages for the rest of your life.

Think about everything you take for granted. Because let’s face it – you’re the coding superstars of WordPress – the people who are a bit confused about how user features in the admin work because you never use them. You’re too cool for the admin. It’s command line or bust.

So it all comes down to this: be kind to the people you work with. Don’t throw them in the ocean to teach them to swim. Help them understand what you’re building together.

Start here: The REST API white paper Siobhan wrote with some peeps from the REST API team.

Thank you!

#feelingrestful

What a day! In between organizing @feelingrestful with my fellow humans I did a 10 minute version of my REST API for non developers talk. Mostly just had fun trolling @joehoyle_ 😋I can’t believe what I do for a living sometimes. Thanks for the pic, @krogsgard.

A Day of REST

Spending the week in Boston with some of my favorite humans for @feelingrestful, the REST API conference I organize with @siobhan_mckeown, @zoe_beardmore & @krogsgard, who took this nice shot on the first workshop day of the event. Thanks Brian! #USA #Boston #WordPress #technology #nomadstories #eventplanner #conference #picoftheday

Spending the week in Boston with some of my favorite humans for @feelingrestful, the REST API conference I organize with @siobhan_mckeown, @zoe_beardmore & @krogsgard, who took this nice shot on the first workshop day of the event. Thanks Brian! #USA #Boston #WordPress #technology #nomadstories #eventplanner #conference #picoftheday

Hello, Boston.

Hello, Boston. You're freaking freezing. And really pretty. The sun's been up all day but I had to jump into the nearest store to get a scarf and another layer of clothes in order to survive. It's -8 outside. Brilliant. The weather app promised spring. What's up with that! But. The view from the Skywalk Observatory at the 50th floor of Prudential Center is quite spectacular. And two floors above, at The top of the hub, I had my first New England clam chowder. Love. Creamy love with potatoes. #USA #Boston #massachusetts #vscocam #vsco #cityline #nomadstories #panorama #rooftop #view

Hello, Boston. You’re freaking freezing. And really pretty. The sun’s been up all day but I had to jump into the nearest store to get a scarf and another layer of clothes in order to survive. It’s -8 outside. Brilliant. The weather app promised spring. What’s up with that! But. The view from the Skywalk Observatory at the 50th floor of Prudential Center is quite spectacular. And two floors above, at The top of the hub, I had my first New England clam chowder. Love. Creamy love with potatoes. #USA #Boston #massachusetts #vscocam #vsco #cityline #nomadstories #panorama #rooftop #view

Bangkok airport, February 6th

Bangkok airport, February 6th. Father and son stop in front of one of the many memorials built for the late king of Thailand Bhumibol Adulyadej. The king passed away in October 2016 and the country is in the middle of its one year mourning period. All over the capital and the islands you can see beautiful memorials of all sizes and the face of the king is everywhere. #throwback #thailand #airport #tradition #memorial #vscocam #nomadstories

Bangkok airport, February 6th. Father and son stop in front of one of the many memorials built for the late king of Thailand Bhumibol Adulyadej. The king passed away in October 2016 and the country is in the middle of its one year mourning period. All over the capital and the islands you can see beautiful memorials of all sizes and the face of the king is everywhere. #throwback #thailand #airport #tradition #memorial #vscocam #nomadstories

Pagans! Happy Granny Match

Pagans! Happy Granny Match & don't forget your martenitsi. (As the picture shows I got an early delivery of mine last night). Double win ;) #Bulgaria #sofia #babamarta #march1st #twins #vsco #vscocam #vscobulgaria #dolls #picoftheday

Pagans! Happy Granny Match & don’t forget your martenitsi. (As the picture shows I got an early delivery of mine last night). Double win ;) #Bulgaria #sofia #babamarta #march1st #twins #vsco #vscocam #vscobulgaria #dolls #picoftheday

On my way home after my first trip to India

On my way home after my first trip to India. Three and a half days passed in what seemed like a constant rush through the streets of Mumbai in between long office hours. I looked at the city as if it was in a museum - through a glass wall (car window). But I saw enough to make me eager to go back and properly explore. Soon. #India #Mumbai #bombay #vscoindia #vsco #powailake #powai #nomadstories #bluesky #skyline #picoftheday #vscocam

On my way home after my first trip to India. Three and a half days passed in what seemed like a constant rush through the streets of Mumbai in between long office hours. I looked at the city as if it was in a museum – through a glass wall (car window). But I saw enough to make me eager to go back and properly explore. Soon. #India #Mumbai #bombay #vscoindia #vsco #powailake #powai #nomadstories #bluesky #skyline #picoftheday #vscocam

No filter. Mumbai

It's been a while since I've posted with no filters or edits. But this shot didn't need any. The clearest bluest sky I've seen in a long time. Mumbai, India. The locals call the city Bombay and this clear beautiful image is probably the least suitable shot to describe it. When you look at the streets it's dirty, noisy, smelly, colorful, bizarre. In the mornings it's covered in a thick misty fog. Then in the afternoon you look up and see this - a perfect, flawless, timeless blue. I find myself staring longer than usual. It's almost time to go home. #India #Mumbai #nofilter #vsco #vscocam #vscoindia #bluesky #nomadstories #skyshots

It’s been a while since I’ve posted with no filters or edits. But this shot didn’t need any. The clearest bluest sky I’ve seen in a long time. Mumbai, India. The locals call the city Bombay and this clear beautiful image is probably the least suitable shot to describe it. When you look at the streets it’s dirty, noisy, smelly, colorful, bizarre. In the mornings it’s covered in a thick misty fog. Then in the afternoon you look up and see this – a perfect, flawless, timeless blue. I find myself staring longer than usual. It’s almost time to go home. #India #Mumbai #nofilter #vsco #vscocam #vscoindia #bluesky #nomadstories #skyshots

Island hopping throwback #Thailand

Island hopping throwback. Our guide & his wife hosted us on their boat for a whole day. Picked us up, took us around the little islands around Koh Lanta, fed us home made lunch. He smiled the whole time. She never smiled and was extremely shy. One thing was clear - it was a family business. And they made us feel welcome. #thailand #kohlanta #kohngai #boattrip #vsco #vscocam #vscothailand #nomadstories #throwback #tbt

Island hopping throwback. Our guide & his wife hosted us on their boat for a whole day. Picked us up, took us around the little islands around Koh Lanta, fed us home made lunch. He smiled the whole time. She never smiled and was extremely shy. One thing was clear – it was a family business. And they made us feel welcome. #thailand #kohlanta #kohngai #boattrip #vsco #vscocam #vscothailand #nomadstories #throwback #tbt