Interactive document environments at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. I’ve just attended a fast-paced, exciting session: “Code the Docs: Interactive Document Environments”, by Tim Nugent & Paris Buttfield-Addison. These are my notes from the session. All kudos goes to Tim and Paris, and any mistakes are mine.

Tim and Paris warned us up front that they speak Australian. Suddenly I feel right at home.🙂 They also write books, are academics, train people in coding, and do other stuff. They’ve noticed that we need better linking between the documentation and the code. Otherwise things break too quickly.

What is an interactive document environment?

Interactive document environments put live code and documentation side by side. You can write content and embed code that runs within the doc.

In the Apple environment, before Tim and Paris started using Swift Playgrounds, they noticed that people got lost. People were switching between docs, code, notes, and couldn’t keep up. So Paris and Tim investigated the tools and made up the term, interactive document environment.

The code, the person’s own notes, and the official documentation all in one place.

Core features:

Live code

Pretty formatting

You can add notes

You can add media such as gifs, videos, etc

It’s real code that you can play with

Swift Playgrounds

Swift is Apple’s new language. Paris and Tim think Swift is the bee’s knees. Swift Playgrounds is a core part of Swift. It’s an interactive coding environment, designed for prototyping, learning and experimenting.

Playgrounds currently supports basic HTML and Markdown for content development.

Tim and Paris gave a demo of Swift Playgrounds. It was impressive to see how you can embed code and see it execute right on the page.

Swift supports emoji, so of course the demo included emoji.🙂 You can also add pagination, with a “Next” link at the end of the page. The code is running all the time, and you see the output on a panel next to the page.

We also saw Apple’s example, called Newton’s Cradle and UIKit Dynamics, which runs in Xcode. (Apple’s announcement blog post has a screenshot and a link to the downloadable demo as a zip file.) The code is live, so you can change it and play with it.

IPython Notebooks, now Project Jupyter

Project Jupyter is an interactive Python coding environment.

It’s used by O’Reilly Media for project Oriole, a learning environment that blends executable code, data, text, and video.

Tim and Paris showed us Regex Golf with Peter Norvig. (Sign in, scroll down the page, and run the code. Change the code and run it again. It’s worth it.)

To try creating content in this environment yourself, download Jupyter Notebook. (The process is a little tricky.)

Strengths and weaknesses

Strengths:

The code and the docs are together, and the code is live. It’s easy to keep them in sync.

You can mix in your own notes. Paris and Tim say it was a real surprise to see how useful people found it, to be able to add their own notes on the docs.

People don’t have to context switch.

Weaknesses:

These environments are new and thus prone to crashing.

They support only Markdown and HTML for content development.

Limited support for languages and frameworks.

No hooks into existing doc tools.

Only really relevant for narrative docs.

Paris and Tim predict that these environments will become more stable and will support more languages and projects. These environments will replace books and articles. There’ll be better support for non-narrative docs. It’s a natural evolution of API guidelines where you give the developers a cURL command to try the API, and even those more advanced docs that supply a button to run the code live.