Hack like a journalist

News reporters are trained in techniques to produce stories that are concise, well structured and easy to follow. How can those same techniques help us write better code?

A presentation first delivered at the London Ruby User Group on Monday 7 November 2015
http://lrug.org/meetings/2015/november/

Transcript

1. HACK LIKE A JOURNALIST Scott Matthewman LONDON RUBY USER GROUP • NOVEMBER 2015 Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
2. EDITORIAL JOURNALISM versus SOFTWARE DEVELOPMENT Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
3. EDITORIAL JOURNALISM versus SOFTWARE DEVELOPMENT Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
4. EDITORIAL JOURNALISM is similar to SOFTWARE DEVELOPMENT Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
5. We need to convey complex information in ways that are comprehensible Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
6. We tell stories Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
7. Programs must be written for people to read, and only incidentally for machines to execute — Harold Abelson, Structure and Interpretation of Computer Programs http://bit.ly/hlaj-abelson Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
8. How do news journalists do it? Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
9. THE INVERTED PYRAMID A template for hard news stories Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
10. Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
11. “This format is valued for two reasons… Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
12. “First, readers can leave the story at any point and understand it, even if they do not have all the details. Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
13. “Second, it conducts readers through the details of the story. — Wikipedia, Inverted pyramid http://bit.ly/hlaj-pyramid Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
14. AN EXAMPLE NEWS STORY Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
15. Joan Littlewood sculpture unveiled outside Theatre Royal Stratford East Matthew Hemley The Stage October 6, 2015 http://bit.ly/hlaj-news Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
16. A sculpture honouring theatre director Joan Littlewood has been unveiled outside Theatre Royal Stratford East. Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
17. The bronze sculpture, called The Mother of Modern Theatre, is located in Theatre Square, next to the east London venue, which Littlewood led for 26 years. It was revealed on October 4, two years after it was commissioned and in the month in which Littlewood would have turned 101. She died in 2002. Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
18. Guests who attended the unveiling included Barbara Windsor and Ian McKellen. Theatre Royal Stratford East artistic director Kerry Michael said: “The sculpture of Joan Littlewood will be a permanent reminder of her great contribution not just to British theatre, but to world theatre. We are proud of our history at Theatre Royal Stratford East and this is the perfect way to celebrate it.” The sculpture was created by Philip Jackson. In November 2013, a public fundraising campaign was launched to raise money for the sculpture. Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
19. Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
20. CLARITY LEADS TO FEWER MISTAKES Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
21. IT’S EASIER TO WORK OUT WHAT TO LEAVE OUT OR MOVE ELSEWHERE Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
22. Guests who attended the unveiling included Barbara Windsor and Ian McKellen. Theatre Royal Stratford East artistic director Kerry Michael said: “The sculpture of Joan Littlewood will be a permanent reminder of her great contribution not just to British theatre, but to world theatre. We are proud of our history at Theatre Royal Stratford East and this is the perfect way to celebrate it.” The sculpture was created by Philip Jackson. In November 2013, a public fundraising campaign was launched to raise money for the sculpture. Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
23. I THOUGHT THIS WAS A RUBY USER GROUP Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
24. Programs must be written for people to read, and only incidentally for machines to execute — Harold Abelson, Structure and Interpretation of Computer Programs http://bit.ly/hlaj-abelson Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
25. We want the code to read like a top-down narrative. — Robert C. Martin, Clean Code: A Handbook of Agile Software Craftmanship Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
26. We want every function to be followed by those at the next level of abstraction, so that we can read the program, descending one level of abstraction at a time as we read down the list of functions. I call this the Stepdown Rule. — Robert C. Martin, Clean Code: A Handbook of Agile Software Craftmanship Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
27. ... [it] helps the program read like a newspaper article. — Robert C. Martin, Clean Code: A Handbook of Agile Software Craftmanship Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
28. SOME EXAMPLE RUBY CODE http://bit.ly/hlaj-rspec-example Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
29. module RSpec module Core module RubyProject def add_to_load_path(*dirs) ... Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
30. def add_to_load_path(*dirs) dirs.map { |dir| add_dir_to_load_path(File.join(root, dir)) } end Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
31. def add_dir_to_load_path(dir) $LOAD_PATH.unshift(dir) unless $LOAD_PATH.include?(dir) end Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
32. def add_to_load_path(*dirs) dirs.map { |dir| add_dir_to_load_path(File.join(root, dir)) } end Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
33. def add_to_load_path(*dirs) dirs.map { |dir| add_dir_to_load_path(File.join(root, dir)) } end def add_dir_to_load_path(dir) $LOAD_PATH.unshift(dir) unless $LOAD_PATH.include?(dir) end Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
34. def root @project_root ||= determine_root end Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
35. def determine_root find_first_parent_containing('spec') || '.' end Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
36. def find_first_parent_containing(dir) ascend_until { |path| File.exist?(File.join(path, dir)) } end Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
37. def ascend_until fs = File::SEPARATOR escaped_slash = "\\#{fs}" special = "_RSPEC_ESCAPED_SLASH_" project_path = File.expand_path(".") parts = project_path.gsub(escaped_slash, special) .squeeze(fs).split(fs).map do |x| x.gsub(special, escaped_slash) end until parts.empty? path = parts.join(fs) path = fs if path == "" return path if yield(path) parts.pop end end Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
38. def root @project_root ||= determine_root end def determine_root find_first_parent_containing('spec') || '.' end def find_first_parent_containing(dir) ascend_until { |path| File.exist?(File.join(path, dir)) } end def ascend_until fs = File::SEPARATOR escaped_slash = "\\#{fs}" special = "_RSPEC_ESCAPED_SLASH_" project_path = File.expand_path(".") parts = project_path.gsub(escaped_slash, special).squeeze(fs).split(fs).map do |x| x.gsub(special, escaped_slash) end until parts.empty? path = parts.join(fs) path = fs if path == "" return path if yield(path) parts.pop end end Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
39. Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
40. Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
41. While this sounds simple, it is difficult to execute in the field because of the avalanche of information that one has to process. So sift through the unnecessary bits to zero in on the most relevant and the most important. — Dev Sukumar, Using the inverted pyramid to write an article http://bit.ly/hlaj-using-pyramid Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
42. Or, in other words… Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
43. HACK LIKE A JOURNALIST Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
44. Other principles where we can learn from each other » Code review & sub-editing » Being your own subeditor » Style guides as living documents » and more… https://scottmatthewman.github.io Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
45. QUESTIONS? Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com
46. THANK YOU scottmatthewman.github.io matthewman.net • @scottm altmetric.com • @altmetric • @AltmetricDev Scott Matthewman / @scottm / @altmetric / @AltmetricDev / scottmatthewman.github.io / altmetric.com