Code the Docs: Interactive Document Environments

Slide 1

Slide 1 text

Code the Docs Interactive Documentation Write the Docs PDX 2016 1

Slide 2

Slide 2 text

Write the Docs PDX 2016 2

Slide 3

Slide 3 text

Tim (unicorn) Paris (not unicorn) @parisba and @the_mcjones Write the Docs PDX 2016 3

Slide 4

Slide 4 text

We Speak Australian Write the Docs PDX 2016 4

Slide 5

Slide 5 text

Some things about us... Write the Docs PDX 2016 5

Slide 6

Slide 6 text

We're academics Write the Docs PDX 2016 6

Slide 7

Slide 7 text

We're academics and game developers Write the Docs PDX 2016 7

Slide 8

Slide 8 text

We're academics, game developers, and technical authors Write the Docs PDX 2016 8

Slide 9

Slide 9 text

We're academics, game developers, technical authors, and programming teachers Write the Docs PDX 2016 9

Slide 10

Slide 10 text

Write the Docs PDX 2016 10

Slide 11

Slide 11 text

Write the Docs PDX 2016 11

Slide 12

Slide 12 text

Write the Docs PDX 2016 12

Slide 13

Slide 13 text

The Situation Write the Docs PDX 2016 13

Slide 14

Slide 14 text

Code + Docs + Notes?! Write the Docs PDX 2016 14

Slide 15

Slide 15 text

People Get Lost Write the Docs PDX 2016 15

Slide 16

Slide 16 text

Write the Docs PDX 2016 16

Slide 17

Slide 17 text

Write the Docs PDX 2016 17

Slide 18

Slide 18 text

Write the Docs PDX 2016 18

Slide 19

Slide 19 text

Write the Docs PDX 2016 19

Slide 20

Slide 20 text

Code + Docs + Notes! Write the Docs PDX 2016 20

Slide 21

Slide 21 text

Interactive document environments? » Swift Playgrounds » IPython Notebooks » ... which are now Jupyter Notebooks » ...and a few others Write the Docs PDX 2016 21

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

We are not experts Write the Docs PDX 2016 23

Slide 24

Slide 24 text

Write the Docs PDX 2016 24

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

Markup in Playgrounds Write the Docs PDX 2016 27

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

Write the Docs PDX 2016 29

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

Demo-Gods I Summon Thee! Write the Docs PDX 2016 31

Slide 32

Slide 32 text

Swift Playgrounds Write the Docs PDX 2016 32

Slide 33

Slide 33 text

Live Demo! Write the Docs PDX 2016 33

Slide 34

Slide 34 text

Live Demo! Write the Docs PDX 2016 34

Slide 35

Slide 35 text

Write the Docs PDX 2016 35

Slide 36

Slide 36 text

Project Jupyter Write the Docs PDX 2016 36

Slide 37

Slide 37 text

O'Reilly Oriole Write the Docs PDX 2016 37

Slide 38

Slide 38 text

Live Demo! Write the Docs PDX 2016 38

Slide 39

Slide 39 text

Write the Docs PDX 2016 39

Slide 40

Slide 40 text

Strengths Write the Docs PDX 2016 40

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

You can mix notes, live code, and docs Write the Docs PDX 2016 42

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

Weaknesses Write the Docs PDX 2016 44

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

Write the Docs PDX 2016 49

Slide 50

Slide 50 text

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