Code the Docs: Interactive Document Environments

Distributing example code and applications with documentation is now easy. There are a million different ways to get code to people: from zips, to GitHub, to gists, and beyond. Code is easy to distribute. But how do we create a better link between example code, and written documentation?
Luckily, clever boffins have come up with some solutions: interactive document environments. These let the live code and the documentation sit side-by-side with one another, the distributed example code is the documentation.
This talk will take a brief look at some of the different interactive document environments out there – mainly IPython Notebooks and Swift Playgrounds – and the various strengths, weaknesses, and caveats of these tools. We’ll also explore the future, and discuss where these tools are going, as well as the implications for technical documentation.

Transcript

1. Code the Docs Interactive Documentation Write the Docs PDX 2016 1
2. Write the Docs PDX 2016 2
3. Tim (unicorn) Paris (not unicorn) @parisba and @the_mcjones Write the Docs PDX 2016 3
4. We Speak Australian Write the Docs PDX 2016 4
5. Some things about us... Write the Docs PDX 2016 5
6. We're academics Write the Docs PDX 2016 6
7. We're academics and game developers Write the Docs PDX 2016 7
8. We're academics, game developers, and technical authors Write the Docs PDX 2016 8
9. We're academics, game developers, technical authors, and programming teachers Write the Docs PDX 2016 9
10. Write the Docs PDX 2016 10
11. Write the Docs PDX 2016 11
12. Write the Docs PDX 2016 12
13. The Situation Write the Docs PDX 2016 13
14. Code + Docs + Notes?! Write the Docs PDX 2016 14
15. People Get Lost Write the Docs PDX 2016 15
16. Write the Docs PDX 2016 16
17. Write the Docs PDX 2016 17
18. Write the Docs PDX 2016 18
19. Write the Docs PDX 2016 19
20. Code + Docs + Notes! Write the Docs PDX 2016 20
21. Interactive document environments? » Swift Playgrounds » IPython Notebooks » ... which are now Jupyter Notebooks » ...and a few others Write the Docs PDX 2016 21
22. Core Features » live code » pretty formatting » ability to add new notes » media rich (gifs, videos, etc.) » real programming, not a special wrapper Write the Docs PDX 2016 22
23. We are not experts Write the Docs PDX 2016 23
24. Write the Docs PDX 2016 24
25. Swift » Introduced 2 years ago by Apple » Currently at version 2.2 » Made open source in December 20151 » Apache License 2.0 » Currently supports OS X and Linux » Windows support on the way 1 For more information on the Swift project, check out their website: http://swift.org/ Write the Docs PDX 2016 25
26. Swift Playgrounds » an interactive Swift coding environment » each statement is evaluated and displayed » designed for prototyping, experimentation, and learning » can be paginated » supports Markdown (yay?!) and HTML Write the Docs PDX 2016 26
27. Markup in Playgrounds Write the Docs PDX 2016 27
28. IPython Notebooks » Interactive Python coding environment » works pretty much the same as Swift Playgrounds » designed for academic and scientific documentation » Supports text, equations, and graphs Write the Docs PDX 2016 28
29. Write the Docs PDX 2016 29
30. Project Jupyter » Successor to IPython » Started in 2014 » Supports multiple languages » Otherwise the same as IPython Notebooks » Used by O'Reilly Media for "Oriole" Write the Docs PDX 2016 30
31. Demo-Gods I Summon Thee! Write the Docs PDX 2016 31
32. Swift Playgrounds Write the Docs PDX 2016 32
33. Live Demo! Write the Docs PDX 2016 33
34. Live Demo! Write the Docs PDX 2016 34
35. Write the Docs PDX 2016 35
36. Project Jupyter Write the Docs PDX 2016 36
37. O'Reilly Oriole Write the Docs PDX 2016 37
38. Live Demo! Write the Docs PDX 2016 38
39. Write the Docs PDX 2016 39
40. Strengths Write the Docs PDX 2016 40
41. Strengths » Code and Docs literally together » ... also notes by the person reading the docs » Can change things on the fly » Mixed Media Write the Docs PDX 2016 41
42. You can mix notes, live code, and docs Write the Docs PDX 2016 42
43. I find the documentation and my own notes living alongside the code to be incredibly handy. It means I don't get lost learning this language and APIs. — feedback from Swift training in Melbourne, May 2016 Write the Docs PDX 2016 43
44. Weaknesses Write the Docs PDX 2016 44
45. Weaknesses » Only Markdown(ish) and HTML(ish) » Kinda crashy... » Limited language/framework support » Doesn't hook into docs tools » Only really works for narratives Write the Docs PDX 2016 45
46. What's next? » Boffins will fix the tech » Be easier to add in new languages & projects » This will replace/become books & articles » Better support for non-narrative documentation » More integration with video and screensharing Write the Docs PDX 2016 46
47. Where to learn more... » On a Mac? Download Xcode from the App Store » Then play in Playgrounds. » On something else? Download Jupyter Notebook » The process is complex » The docs for this are bad... » or go to: https://try.jupyter.org Write the Docs PDX 2016 47
48. O'Reilly Oriole » Try Regex Golf: » oreilly.com/learning/regex-golf-with-peter-norvig » Learn more about Oriole: » oreilly.com/ideas/oreilly-oriole-learn-alongside- innovators-thought-by-thought-in-context Write the Docs PDX 2016 48
49. Write the Docs PDX 2016 49
50. Thanks! » Questions? Find us up the front.. » .. or find us on Twitter! » @the_mcjones (horse) » @parisba (not horse) » Slides and notes will be online at: » http://lonely.coffee and » http://blog.paris.id.au Write the Docs PDX 2016 50