Much Serendipity Day code pain and learning


I built this! It was little but made me happy. Grab Story was the API part.

So…. Code Year!

Ever since friend Casey attempted Code Year and nearly drove himself over the edge, mentions of the start-programming-in-2012 idea have popped up regularly in my streams. I haven’t observed¬†a formal Code Year, but I’ve been coding more this year than I have in a long time.

The last time I coded anything more than HTML and CSS from scratch was probably Mr. Blair’s computer-science class, my junior year of high school. The last time I wrenched apart and reassembled other people’s scripts was senior year of college and the couple years after. Life, at a certain point, became more about working with coders than being one. I really came to like working with news coders, seeing their challenges.

But as you know, at work we have something called Serendipity Day.

A few times throughout the year in our Digital Media division, we stop all projects, block all calendars and work a day on whatever we feel might benefit NPR. For the first Serendipity Day, last spring, I teamed with my UX colleague Vince. We came up with a new way of running the NPR homepage. Our team coded and implemented that tool in December, which was cool. For the second Serendipity Day, I applied human-centered design to NPR digital consumption and time-of-day factors. For the third, most recent Serendipity Day, I decided to code.

I worked all the time with PHP developers on our publishing systems (aka storytelling tools aka content-management system), so I decided to learn PHP. I’d never looked at PHP code beyond a little WordPress.

For a problem to solve, I decided to tackle the NPR homepage’s blog rotator. The three-frame piece, in the top-right of the page, promoted our blogs well. But it was awful to maintain. For each frame, an editor had to enter the post’s headline, the post URL in two places, the main post image, the blog’s logo, the blog’s overall URL in two places, and the blog’s tagline. And the editor had to do all this by hand in HTML.

This problem wasn’t NPR’s biggest or most complicated, by far. A coder could have handled it easily. But it was well-sized for me to learn on.

So.

The rotator had three frames, but each frame had two levels of data. For each frame, there was the post’s metadata, changing each time. Each post was then tied to an NPR blog: a finite set of blog metadata.

In tackling this problem, my main goal was workflow efficiency (sanity). To learn, though, my secondary goal was getting to efficiency in a way that built on existing content data while still allowing editorial flexibility.

So. I started small. Then I worked my way out. Here were my steps.

1. Managing post-level information:

-Researched how PHP interacts with data files.
-Printed one piece of data on the screen.
-Saved one hard-coded piece of data into a file.
-Retrieved that piece of data and printed it on the screen.
-Save two pieces of data to a file, delineating between them.
-Returned the two pieces from the file, split and displayed them.
-Saved an array to file. Two items with two pieces of data each.
-Returned as much and split the data into its two dimensions.
-Researched how PHP manages form elements.
-Took user entry from the screen to update the data.
-Returned the data to the user’s entry fields for re-editing.
-Expanded to saving three items, like the three rotator frames.
-Expanded each frame’s data to handle the post-level data.

2. Automating a post’s blog-level data-entry:

-Set up the retrieval process with a second set of data.
-Put default information about our blogs into that set.
-Researched how PHP and Javascript interact on forms.
-Updated the front-end with a dropdown to select a blog.
-Set the form to grab a blog’s default into upon selection.

3. Generating a useful output:

-Researched how PHP outputs large blocks of text.
-Wrapped the saved data into output HTML.
-Printed the output HTML to a text box on the screen.
-Wrapped the saved data into the rotator’s exact HTML.

4. Adding blog-level flexibility:

-Added a custom option to the set, not bringing defaults.
-Wired form to expand for input upon custom selection.

5. Speeding post ordering:

-Attached a number to each line of the post data.
-Set up user input to edit the number.
-Saved the numbering.
-Rewrote the data packing/unpacking to allow order edits.

6. Publishing automatically:

-Saved the generated output HTML into a file.
-Added a front-end option to publish or not publish.
-Added a back-end switch to act on that choice.

7. Speeding the post entry:

-Researched how PHP can retrieve data from APIs.
-Researched how the NPR API works.
-Used the  NPR API and a story ID to retrieve a headline.
-Used the same to retrieve a story’s URL and blog ID.
-Used the same to retrieve a story’s primary image.
-Post-processed to return the correct crop of the image.
-Post-processed to remove trailing URL parameters.
-Added story ID entry to the user’s screen.
-Sent the ID upon generation to API.
-Saved the returned data and returned it to the screen.

8. Improving the interaction experience:

-Borrowed CSS from our publishing tools.
-Adjusted form for appropriate content lengths.
-Added color to the shortcut API query.

9. Preparing the demo:

-Input that day’s live rotator information into the tool.
-Linked the tool on the internal Serendipity demo page.
-Wrote two minutes worth of remarks about my project.

Then time was up.

By the end of the project, I had a fully working script that generated fully working rotator code. What took 15 minutes of entry previously came together in a minute now. While the rotator was only a small part of our workflow, not even crossing platforms, it prevented editors from spending time on more critical work that would cross platforms. Sometimes you had to deal with the present to get to the future.

Looking back, the process was… interesting.

First, it ruined my life for a couple days. There was very little sleep. I saw more error messages than I’d ever seen in my life. I got so much wrong over and over again. There was no paid overtime for this work.

Second, I kind of enjoyed it. I learned a ton. The code kicked my ass until I got it right. I went from knowing nothing to knowing something.

Third, I wanted to know more about how real coders would have done this work. For instance, using SQL to store the data would have been easier to code, but it felt like overkill for just three frames. Also, when it came to reordering arrays and capturing information from an API, my methods worked but didn’t feel as sound or efficient as in other parts.

Fourth, I felt most of my final code was more sound and efficient that I had expected at the start. I wanted a code-review to find out for sure.

And that was where things left off. The demos were much fun, seeing several dozen NPR Digital individuals and small groups present briefly on how they’d spent their day-plus. I asked a senior developer if she could conduct a full code review on what I had, and she was amused and said yes. We hoped to find time in schedules this spring. What I had wasn’t ready for 24/7 newsroom action, but maybe it was close.

Leave a Reply

Your email address will not be published. Required fields are marked *