Author Archives: Sarah Maddox

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.

This talk looked at two examples in particular: Jupyter Notebook (formerly known as IPython Notebook) and Swift Playgrounds.

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.

To use Playgrounds, download Xcode from the Apple Store.

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


  • 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.


  • 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.

Thanks Tim and Paris, this was an entertaining and informative talk. Notes and slides will be at and

Internal docs for startups at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. I’m at a session titled “Move Fast And Document Things: Hard-Won Lessons in Building Documentation Culture in Startups”, by Ruthie Bendor.

Ruthie Bendor‘s session was about strategies for writing internal docs at fast-moving organisations. Ruthie is one of the brave engineers who attended a conference full of tech writers!

Internal tech docs are things like README files and wiki pages, containing instructions for setting up engineering environments, and so on. They’re what we write for our colleagues to enable us to build upon our work. Even our future selves will find this documentation useful.

When you work at a technical startup, saying “that’s not my job” doesn’t work.

Ruthie told us a few stories of how she’d experienced internal docs as a software engineer. A telling example was when Ruthie worked at an agency. In that organisation, most of the programs Ruthie wrote weren’t meant for production – they were demos for customers, to be thrown away after they’d met their purpose. In this case, there was no need to write much documentation. This is in contrast to working on production code and procedures, where docs help the company progress.

Another story was about Ruthie’s first few days at a startup, where there was no internal documentation to help her get started with all the tools and processes. She stumbled through the first tasks of getting code committed, repeatedly having to bother other people when she messed up the code base.

Based on her experiences, Ruthie suggests four steps to writing internal documentation for a fast-moving organisation.

  • Figure out what’s broken. Don’t guess. Find out what the rest of the organisation thinks is broken, rather than going on your own assumptions. You’re probably wrong! Find out whether the team values tech documentation, and if not, why not. Possible reasons why engineers may not value docs are the belief that internal docs get outdated too quickly, or that all engineers have the same technical background.
  • Figure out why your organisation cares about fixing its internal technical docs. You may think the docs will make the software last as long as possible, or will help onboard new staff. But these points don’t apply to fast-moving startups. Startups are focused on making the product. Ruthie learned that the people in her organisation value learning from each other. This is why they care about internal docs. What you document and how you document is an expression of your company culture.
  • Couch your solutions in the organisation’s values. Ruthie says this is hacking in the best sense: how to get the results you want with the tools you have, and not necessarily in the traditional way. Think about videos, weekly show and tells, etc.
  • Iterate. At every inflection point of the organisation, reevaluate the values, rinse, repeat.

Incidental learning from this session: The “bus factor” is the number of people who can be unexpectedly lost by a project before the project collapses. It’s the number of people who can be hit by a bus without the organisation going out of business.

Thanks Ruthie! This was a fun and informative session.

Values of effective tech writing teams at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. One of the sessions I attended is “7 Values of Effective Tech Writing Teams”, by Joao Fernandes. Here are my  notes. All credit goes to Joao, and any mistakes are my own.

Joao Fernandes started by saying that success and effectiveness are words without meaning, unless you have a specific goal in mind. So, what’s the goal of tech writing?

Some answers are:

  • Teach people how to use a product.
  • Explain complex information in a clear way.

But those goals aren’t ambitious enough, says Joao. There’s something more profound that guides us. Our users don’t want to read the docs. They want to use the product. So Joao proposes the following goal for tech writers:

Help build products that need no documentation.

Given that premise about our goal, these are my notes on the rules that Joao discussed:

Be the CEO of the docs. Define a vision for the docs, communicate that vision to all interested parties, and make sure others follow it. Make sure you schedule time to do strategic work, as finding that time will be difficult otherwise.

Know the market, product and users. Understand the need that your company is trying to fill in the market.

One of the main points of this session is that we need to decide what documentation is required (the answer may be, very little), and where best to put it (the answer may be that the doc is part of the product rather than traditional documentation). Joao suggested we should apply the 80/20 rule when deciding which docs are required.

Another point is that effective tech writers ask “why” all the time.

Effective tech writers use words as tools, in the same way as developers use programming tools. A natural language is an interesting tool, because it allows for the transfer of knowledge from one person to another. Sometimes the transfer doesn’t go too well. We can complement language with other tools, such as diagrams. And we can adapt the language to make it more effective.

Sharing knowledge is also an important part of an effective tech writer’s role. Coach others, and create resources to help new members of the team.

Thanks Joao for a beautifully presented session!

A readable README file at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. These are my notes on a session by Daniel Beck, titled “Write the readable README”. All credit goes to Daniel, any mistakes are my own.

Daniel Beck writes tech docs for developers and sys admins. A lot of his work is in deployment guides. In the course of his work, Daniel comes across many README files. In self defence, he decided to research README files, and looked at more than 200 of them. He analysed them from the following points of view:

  • The type of project the README documents
  • Other files accompanying the README file
  • The markup used in the README
  • The topics covered
  • Links to other files and documents
  • Images in the file: logos, other visual aspects
  • What was good and effective
  • What was bad or not helpful
  • How did the README make him feel?

Daniel found that README files vary in quality. Some of them are even hostile to the reader. Some of them miss vital information, such as project name or location of the project. Some READMEs are very old – the oldest one dates from 1974! Typically, they’re Markdown files that contain a lot of information in visually unappealing form.

Tools like GitHub and Bitbucket have brought README files back to life.

The best READMEs give you confidence about a project. They help the reader identify and evaluate the project. They help you get started (use the project at least once) and engage with the project.

So, README files are useful, and are something we’ll probably need to create. Daniel cautioned us against relying too heavily on templates for README files, as a template may make you think that you’ve included everything you need even though there are some gaps.

Instead, Daniel has prepared a README checklist, available on GitHub. It’s a useful document, in that it suggests parts you may need in your README file, and also describes what to put in each part, tips on how to find the content for that part, and guidance on when you may need the part. Daniel also pointed out the template for contributing guides for open source projects.

Thanks Daniel for an entertaining and instructive talk, and for a useful checklist!

API documentation tools at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. Today is a kind of pre-conference day. There are doc sprints, and an API docs meetup.

At the moment, I’m in the API docs meetup. The day starts with a few set talks, to be followed by “open space” sessions. Here are my notes on the first couple of talks about documentation tools.

Docbox and retext-mapbox-standard, from Mapbox

The first talk of the day was “REST API documentation generator” by Rafa of Mapbox. The Mapbox team writes the documentation in Markdown. In the background is Jekyll and GitHub pages. Rafa walked us through a couple of pages of the documentation, which includes code samples, generated for various programming languages, as well as hand-written words.


  • Docbox: An open source documentation tool for REST APIs. It’s a JavaScript application written in React (a JavaScript library for building user interfaces). It includes automated testing of the code samples in the docs. This looks like a pretty interesting collections of tools to explore.
  • retext-mapbox-standard: An open source tool that checks for grammatical consistency and correct spelling. This is implemented as tests, run against the documentation. It’s written in JavaScript.

Rafa said this set of tools works really well for collaboration on writing the docs.

There was a lively discussion at Rafa’s session, with a very engaged audience. We discussed topics such as reader feedback, automated testing, size of the doc set, versioning, and more.

All this information was packed into half an hour! Thanks Rafa for a great session.

Tight coupling of API docs: YAML and custom tooling

The next session was “API documentation tooling at Capital One” by jennifer rondeau. Jennifer talked about the options and challenges for tight coupling of API documentation. Creating docs manually is not optimal. To keep your docs up to date, you need automated ways to sync your docs with your code. That’s what Jennifer means by “tight coupling”. In this talk, she’s focusing on the reference documentation, and specifically REST API reference docs.

You need to automate,  but be ready for the areas where you need human intervention:

  • Prefer a design-first rather than a code-first approach to creating an API. Jennifer’s team uses Swagger. For the most part, they use Swagger for naming conventions and exposing usable external APIs, not so much for the architectural considerations. Jennifer gave an example: Assume your development team creates a parameter that currently has only one permitted value. The parameter exists to allow for future expansion. In the external docs, remove the parameter.
  • Note that Swagger YAML is human-readable, but not really. Jennifer emphasises that Swagger-UI is not a documentation tool. Swagger is most useful for generating server and client code. So, you need doc tooling. Jennifer’s team uses tooling that converts the Swagger YAML to a markup format (Markdown or HTML), and puts it all in a single file. Then there’s a manual step to clean up the text in the generated export files. You need to clean up the arrangement of the file, then expand descriptions and so on.

Jennifer walked us through the Capital One Platform documentation, and particularly the SwiftID webhooks, which is the output of the above processes. The hello world content is manually created. The source is all AsciiDoc, either generated from the YAML or hand-written. A member of the audience commented that it was good to see the manually-written content integrated with the generated docs.

Next, Jennifer discussed a different approach: creating documentation from tests. Jennifer talked about spring-restdocs, which adds the stubs for the documentation. You can then go and add the text later. How you automate your docs depends on how you’re building your API. The docs-from tests approach is useful particularly if you use the code first approach to creating an API. Your docs must exist in order for your tests to pass.

Thanks so much, Jennifer, for these tips on how to Swagger, and the hint about sprint-restdocs.


Get every new post delivered to your Inbox.

Join 1,717 other followers

%d bloggers like this: