Tool documentation style validation design ProPublica’s News Apps Guides

A new five-part documentation series

Yesterday morning, the ProPublica apps team released a series of documents outlining their coding philosophy, app design and development practices, data validation techniques, and more. We spoke with Scott Klein about the docs’ lineage and how he and his team made the time to create them.

Klein outlined a process that began informally as the apps team first formed and documented their initial processes and stylistic choices in scattered notes and emails. During a recent P5 project with Digital First Media’s Peggy Bustamante, Klein found himself going back over ProPublica’s informal set of coding practices and spotted a chance to turn his notes into more formal documentation. “And you know how these things snowball,” he said, introducing the five-document series that evolved out of his initially simple plan.

The Guides

Although they’re written under specific bylines, Klein emphasized, the new guidelines codify principles and practices that have emerged from the work of the entire ProPublica news apps team. The guidelines are divided into five parts:

  • The style guide collects both copy notes and ProPublica data-display practices: always show data sources, for example, and always include concise top matter. The details of bylines and labels are included, but so are major data display choices, like which chart to use in a specific situation—and the style guide even takes a crack at formally distinguishing between news applications and graphics.
  • The brief design overview offers three brief orienting techniques for those about to design a news application, focusing on ways to find the right starting point and direction for a new app.
  • The coding manifesto, co-authored by Klein and Jeff Larson, breaks down a minimalist set of core practices covering speed and caching, browser and device compatibility, responsive design, source control, and documentation.
  • The social tags provide ProPublica’s standard set of metadata for Twitter and Facebook.
  • The data bulletproofing guide, written by Jennifer LaFleur, collects the news apps team’s data validation and handling practices, supplemented by advice from journalists at the Washington Post, the Orange County Register, and the Fresno Bee, along with a supplemental reading list.

The ProPublica docs are an open, forkable resource hosted on GitHub, waiting to be adapted for incorporation into the practices of other development teams inside (and perhaps even outside) newsrooms.

comments powered by Disqus