Blog Archives

Write the Docs NA 2016 wrapup

This week I attended Write the Docs NA 2016, which wrapped up a couple of hours ago. This post is a summary of impressions, with links to my notes on some of the sessions I attended.

One thing that strikes me about Write the Docs is that I’ve spent much of my time talking to people. This is partly because half of each day is devoted to unconference sessions as well as formal presentations. In the unconference sessions there’s a facilitator rather than a speaker, so everyone can contribute to the discussion. Another reason I’ve done so much talking to people is that there are so many interesting, friendly, enthusiastic people to talk to.

There were approximately 400 attendees. They’re people who love documentation – that is, people who know its value. Based on a show of hands at the introductory session, approximately 60% of the attendees are technical writers and about 15% are software developers. Others are UX specialists, support engineers, librarians, knowledge management specialists and more.

Another thing that strikes me is that the pre-conference activity was a half-day hike through the forested hills around Portland. Now, that’s my kind of activity.

The sessions

These are the notes I took from some of the sessions I attended:

Doc sprints and API doc meetup

On the first day of Write the Docs, we gathered at Centrl Office to write docs and talk about API documentation. It was great chatting to so many enthusiastic, knowledgable writers. People got together and contributed to open source documentation with Mozilla, Google, and more. We filled three rooms to the brim. This photo shows the scene early in the day, before most people had arrived.

write-the-docs-writing-day

Conference venue

Days two and three were at the Crystal Ballroom. What a lovely venue! Here’s the view from the stage looking out across the conference attendees.

write-the-docs-ballroom

A closer view of the murals:

write-the-docs-murals

A chandelier:

write-the-docs-chandelier

More about Portland

My travelling bookmark, Mark Wordsworm, has some pictures and words about the city: Lost in Portland, Oregon.

Thanks

A huge thank you to the organisers of Write the Docs NA 2016. This is my first experience of a Write the Docs conference. I’ve wanted to attend for a couple of years, but it’s a long way from Sydney, Australia, to any of the conference venues. This year, everything came together and here I am. It was a great experience, and well worth the trip. Thanks!

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

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.

Thanks Tim and Paris, this was an entertaining and informative talk. Notes and slides will be at lonely.coffee and blog.paris.id.au.

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.

Tools:

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

Webinar on API technical writing with STC India

Are you interested in learning about APIs and API technical writing? Join us for a webinar, hosted by STC India. I’ll demo a couple of APIs and discuss the role of a technical writer in this area of the software industry. We’ll look at examples of API documentation, and discuss what type of documents an app developer expects when using an API.

The title of the webinar is “Introduction to API Technical Writing”. It’s intended for technical writers who know little about APIs (application programming interfaces) and want to explore the field of API technical writing. My hope is that, after attending this webinar, you’ll have the knowledge and tools you need to head off on your own explorations.

APIs (application programming interfaces) make it possible for applications to share information with each other. You could say that APIs are the communication channel of the online world. Developers need help hooking their application up to someone else’s APIs. We, as technical writers, give them that help.

Recording of the webinar [Update on 10 April 2016]: The recording of the webinar is now available on YouTube: Introduction to API Technical Writing.

Registration details: Sign up for the webinar, and read more about it on the STC India site.

Date and time: Friday 18 March 2016, at 1pm Indian time – that’s 6.30pm in Sydney. The session lasts one hour.

Who can join? Anyone. It’s free of charge, and you don’t need to be a member of the STC.

Topic overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer.
  • Our audience – the developers who need our documentation to use APIs in their applications.
  • The types of API we might be asked to document.
  • Demos of 2 APIs that you can play with yourself.
  • What API documentation consists of.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.

Hope to “see” you at the webinar.:)

New Android app for the technical writing community

I’m super excited. I’ve just launched my first app on the Google Play Store: Tech Comm on a Map. It’s for technical communicators, to help us see what’s happening in the tech comm world. 

Tech Comm on a Map - Android appSee what’s happening in tech comm around you. If you know of something that’s missing from the map, you can add it yourself using the “Add event” option: a conference, meetup, business, or other item of interest to technical communicators.

As well as the Android app, Tech Comm on a Map is available on the Web too. The two apps use the same data source. The Web-based version has been around a while. The Android app is new and shiny: I published it to the Google Play Store this weekend.

I’d love it if you’d try it out. It’s even better if you have some events or other items of interest to share with the tech writing community, by adding them to the map. All additions are moderated before they appear in the app.

 

Get it on Google Play

 

Contributors to the project

The Android app is an open source project on Github. To kick off the project, a group of us got together during a hackathon and built the basics of the app.

Disclaimer

Although I work at Google, this app is not a Google product.

Follow

Get every new post delivered to your Inbox.

Join 1,695 other followers

%d bloggers like this: