Recording of Innovation in Technical Communication keynote at tcworld India 2015

by Tom Johnson on Mar 18, 2015
categories: api-doc • innovation • podcasts • web-design

The following video is a recording of the keynote presentation I gave at tcworld India 2015 in Bangalore.

In this presentation, I lay out a (hopefully persuasive) case for a new direction that tech comm writers can take in their tooling, arguing that the hotbed of innovation taking place today is with web tools and web platforms, not so much in the tech comm space, which seems to follow its own independent development track outside of web tools.

You can flip through my slides here:

Or clone and fork the slides from Github here: https://github.com/tomjoht/innovation.

Summary

The general outline of the presentation is as follows:

• Startups are great places to innovate.
• Innovation can be divided into at least two types: sustaining innovation and disruptive innovations.
• Disruptive innovations operate in the background as their technology matures; eventually they overtake the mainstream technology.
• Mainstream technology operates in a different value network and can't necessarily sink time and resources into research and development because they're too busy working on the next feature for their sustaining innovations.
• Innovation has a number of dilemmas — the time required to innovate can sideline your existing projects; you might have too much legacy content to make a change; you might not have the engineering background to build the tools you need; and you might be putting your career in jeopardy by investing in an obscure technology.
• There's a lot of pressure to follow the mainstream technology, especially DITA. I implemented DITA and worked with it for several projects, but eventually I found it too restrictive. Everything I tried to do required all kinds of hacks and workarounds.
• In looking in the space I was working in (API documentation), XML seemed to be an older technology not really used much. Instead, all the web developers are pretty much creating platforms that process HTML, Markdown, and JavaScript. REST APIs return responses in JSON (JavaScript Object Notation), not XML, and that communication protocol seems to reverberate throughout the web developer's toolchain.
• In looking at how people publish on the web, I noticed that many people use Github to share and develop code. Github is considered one of the most revolutionary technologies of the web. It allows developers to share, distribute, clone, and fork code, which gives rise to a lot of innovation. Developers don't work so much in isolation anymore. The code becomes living code samples on their local machine — you can continually update them as the origin gets updated. This phenomenon is referred to as "social coding."
• There's no reason why documentation can't be treated as code as well. Instead of working in binary file formats (which only computers can read), you can work with text-file formats, using a text editor (such as Sublime), committing your documentation to a code repository to share, version, and collaborate, and publishing via build scripts run on the command line.
• In fact, you can even create PowerPoint presentations in code. This presentation uses Reveal JS instead of PowerPoint. Everything is in code, using text-file formats. You use simple section elements to define different slides, and h2 elements for titles, and so on. Working in code is so much more satisfying than working in frustrating rich text editors that constantly munge your content and require you to dig around in the source to fix formatting issues. (To view this presentation in its text-file format, you can get the source code here: https://github.com/tomjoht/innovation.)
• In looking at up and coming web platforms, static site generators (Jekyll, Octopress, Middleman, Docpad, + dozens more that you can find listed on staticgen.com) embody the trend of treating content as code. These static site generators allow you to compile your code locally, giving you a preview server where you can see your local build frequently update. Some static site generators, like Jekyll, use templating languages like Liquid in order to do more advanced logic, such as content re-use, loops, if-else statements, variables, and more.
• You can do most everything you do with DITA (in terms of re-use, keyrefs, conditional filtering, etc.) using Jekyll. It's just a different approach that follows a much more web-centric model.
• I created a theme based on Jekyll for my documentation projects. It leverages Bootstrap, jQuery, and other web technologies. It's flexible in that you can add JavaScript wherever you need to in the code. You write in Markdown, HTML, and Liquid. You can check it out here: https://github.com/tomjoht/documentation-theme-jekyll. Feel free to clone and fork it.
• Imagine a world where many tech writers put their help systems in Github repositories and allowed others to clone, fork, share, and redistribute them. It would lead to a great deal of innovation and community.
• Although Jekyll might not be the disruptive tech that displaces mainstream tech comm tools, my larger point is to look beyond the tech comm bubble. Look at the innovation taking place on the web, and find ways to plug into that web's momentum.