Archives for category: Code & Development

If you want to understand someone, my advice is to sit next to them and solve a very hard problem together. You will learn who they are by watching how they think.
— Michael Lopp

PyGotham and the Q&A that followed, I’m finding more reasons than ever to read Michael Lopp’s books and blog, Rands in Repose.

The tension between those who make digital products and those who don’t is a systemic problem that seems to stymie every industry, yet so few people know how to resolve it — and resolve it at scale. There must be a collection of good advice somewhere. If not, it’s probably time to start one. What do you say?

(Photo: Ed Yourdon/Flickr)

Poynter.org just published my how-to piece on reading API documentation.

It’s directed at readers with little to no coding experience. I hope the intended audience finds it helpful. The example I used — looking up New York Times “Harry Potter” movie reviews — was a fun one, rather than something more serious, because doing fun things lowers the barrier to getting started.

Reading API documentation takes patience and tenacity. Even the most experienced developers I know will sometimes come across documentation so poor that they spend a lot of time guessing at how the API works. So don’t feel daunted. Practice instead.

I’ll post a couple follow-up exercises here on Ricochet, but get started now by heading over to the beginner’s guide for journalists who want to understand API documentation.

Update:
Thanks for all the retweets, comments and link pass-alongs. Keep them coming, and feel free to ask questions and suggest other tutorial topics in the space below.

Michal Migurski of Stamen sent me some thoughts about writing APIs based on my post, which makes me think there might be hope for the way API documentation will be written in the future.

In the meantime, if you’re responsible for writing API docs — or technical documentation of any sort — Jacob Kaplan-Moss’s “Writing Great Documentation” instructional series is mandatory reading.

Jacob’s name might sound familiar to you: he’s one of the co-founders of Django, a Web development framework created by journalists and developers as a tool for doing data-based journalism.

Photo: Sean Dreilinger/Flickr

Over the weekend, I went to Jer Thorp’s Processing and data visualization workshop to dig deeper into the program.

While I don’t have new code to show yet, today I started looking for additional learning resources. Artist Marius Watz is publishing a free series of Processing primers on Modelab. The examples are fully commented, so even if you’re fairly new, it’s easy to follow along.

Daniel Shiffman, who wrote “Learning Processing: A Beginner’s Guide to Programming Images, Animation, and Interaction,” is planning a new book, due to be published this summer. It’s on Kickstarter:

Daniel’s got tutorials and excerpts from his current book online for those curious about his writing style and looking for additional examples to learn from.

Have some additional sites and sample files you’d like to share? Leave a note and help create a standing resource.

I don’t know about you, but December’s been pretty crazy for me. Between trying to maintain a healthy work-life balance (yeah, right) and trying to learn new things, I was shocked to realize Christmas is next week.

Egad.

Nevertheless, I’ve a little treat for you: Do-it-yourself polka dotted Christmas wrap and digital wallpaper, made with Processing. A sample’s below.

Take your pick of default sizes: 960 x 600 pixels or 1280 x 800 pixels.
Christmas polka dots
I learned a few things while making this project:

  • What they say about coding is true: You’re more apt to learn something if you’ve got a project in mind.
  • The initial bits of Processing are pretty easy to understand. But then there’s trying to grok random (not so bad) and shuffle (oy).
  • Coffee is good. Sleep is better.

To try Processing for yourself, copy my code from Github and paste it into the Processing.js Web IDE, or download Processing and tweak it locally.

Creative Commons LicenseThe code is released under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.

Turns out this weekend is going to be hacktastic. If you’ve never been to a hackathon before, there are plenty of choices. Among them:

  • Dec. 4 is Open Data Day, where participants will use open public data to create all sorts of projects all over the world.
  • It’s also the start of Random Hacks of Kindness, a two-day international event for projects related to natural disaster risk and response.
  • Not to be outdone, The New York Times holds its first-ever TimesOpen Hack Day on Saturday too.
  • Leave it to San Francisco to hold Cloudstock, “the Woodstock for Cloud Developers.” That hackathon happens Dec. 6.

If you’re a developer who’s never been to a hack event before, register and go if an event sounds well-organized and interesting. Meet people. Find the ones you like. Build stuff together.

If you’re a journalist who’s never been to a hack event before, you’re probably wondering what the heck a hackathon is.

Wikipedia’s got a whole page about it. Basically, it’s an event for people (usually coders) to get together, hatch an idea, and produce a working model (a “hack”) within a fixed period of time using ingenuity, cooperation and whatever means are at their disposal.

Some hackathons are “open,” meaning you can build what you want. Others have themes and parameters. There are those, like next weekend’s OpenDoor Hackathon, that call for hardware hacks. Others, like Longshot magazine, are about storytelling and are definitely within the comfort zone of any journalist willing to hustle and forgo a little sleep.

There are way more techie hack days than there are journalist-specific hack days. But that does not mean you, Reporter/Editor/Visual Journalist-lacking-coding-skills, should be timid.

Pick the right event, and you’ll find yourself among people who are willing to teach you what you don’t know, or at least explain what they’re doing as they’re doing it.

While you’re putting the project together, you’ll discover opportunities to contribute your own knowledge and skills: looking for information, sharing subject expertise, asking incisive questions, picking through data troves, realizing when an idea needs to evolve (or as the startup people like to say, “pivot“).

You might feel like you’re barely hanging on during the first couple of hack events you go to. But the more you go, the more you’ll learn where your own hacker interests lie. Who knows? You might find yourself learning to program and creating data visualizations and making maps using something other than Google Maps.

Want some inspiration? Two years ago, journalist Jeremy Singer-Vine was not a programmer. But in two years, he learned enough to make a tool that’s been used by Slate and NPR to help the public make sense of financial jargon.

Cool and useful, right?

Additional links:

Switch to our mobile site