Code the Docs: Interactive Document Environments

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.

C3a4fc30c6f27aeee94dcdf03c689dd7?s=128

Tim Nugent

May 24, 2016
Tweet

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