You are here

idratherbewriting.com

Post a note under our blog aggregation requests if you want your blog added to our aggregator. Please provide the RSS feed URL and the title of your blog.

Subscribe to idratherbewriting.com feed
Updated: 1 hour 21 min ago

How to create a help API

Wed, 03/04/2015 - 03:20
In my last post in this series, I talked about static site generators as a platform for help. In this post, I want to explore Help APIs, which is actually something in part enabled by static site generators. To put things in context, the web is sort of a giant API. Each browser functions as Continue Reading » (more)

Static site generators start to replace web publishing platforms like WordPress

Fri, 02/27/2015 - 11:16
In the previous post in this series on innovation, I highlighted some web tools worth exploring for help systems. In this post, I want to dive into one of the latest trends with web tools: static site generators. The Rise and fall of web publishing platforms For the past 10 years, web publishing platforms with Continue Reading » (more)

Some web tools worth using in help solutions

Thu, 02/26/2015 - 16:17
In the previous post in this series, I argued that piggybacking onto the innovation of the web requires us to use the same web platforms that web developers create, support, and maintain. In this post, I want to mention a few web technologies worth checking out. jQuery jQuery is a JavaScript library that provides functionality Continue Reading » (more)

Piggybacking onto the innovation of the web

Tue, 02/24/2015 - 11:28
In the previous post in this series, I looked at the five major technological innovations of the past decade and asked how tech comm plugs into each of them. In this post, I want to explore ways to piggyback onto the innovation of the web. Challenges in hacking A few months back, I was exploring Continue Reading » (more)

Microsoft and the last 5 great technological innovations

Fri, 02/20/2015 - 00:50
I recently came across an interesting article by Jason Calicanis called Microsoft is interesting again — very. It talks about why Microsoft has lost out on the last 5 major technical innovations, and how they are poised to make a comeback. Calicanis writes: Microsoft has been largely dead to Silicon Valley because for the past Continue Reading » (more)

Interactive video workshop in San Jose this Saturday, 1-5pm

Thu, 02/19/2015 - 11:09
If you’re in the San Francisco Bay area and are interested in learning more about creating interactive video tutorials, check out the Best Practices when Creating Interactive Video Tutorials Workshop, sponsored by the STC-Silicon Valley chapter. The workshop will be held at the West Valley Branch Library, 1243 San Tomas Aquino Rd., San José, CA Continue Reading » (more)

The genius of Github and how it can transform tech comm

Wed, 02/18/2015 - 11:46
This is post #5 in my ongoing series on innovation in tech comm. In the previous post, I argued that many web developers and designers seem less savvy and eager to use XML in the platforms they develop, preferring instead to focus on HTML5, CSS, JavaScript, and JSON. In this post, I explore Github and Continue Reading » (more)

XML and the web: drifting farther apart?

Fri, 02/13/2015 - 10:26
In my previous post in this series, I explored how the web empowers everyday people as technical writers. I’ll return to this idea in a major way, but first I want to note some other trends that will plug in to this ongoing discussion on innovation. In this post, I want to dig a bit Continue Reading » (more)

The only significant innovation for tech comm

Fri, 02/13/2015 - 10:02
When I surfaced the topic of innovation on my blog (in the first post in this series), some people noted that the only really noteworthy innovation to affect technical communication in the past 20 years is the web. Mark Baker, author of Every Page Is Page One, made one of the most insightful comments. He Continue Reading » (more)

A long list of technical innovations semi-relevant to technical writers

Thu, 02/12/2015 - 00:15
The degree of innovation over the past two decades is so immense that you have to dramatically narrow the scope to even have a fruitful discussion. I’m going to look specifically at technical innovations that might be semi-relevant to technical communicators. You can somewhat draw a line between innovation with tools and innovation with ideas. Continue Reading » (more)

Sustaining and disruptive innovations

Tue, 02/10/2015 - 11:50
What is innovation? When we talk about innovation, we usually refer to new tools, processes, or other techniques that improve how we do something. For example, in software development, the agile software process is an innovation from the waterfall method. Some innovations are more radical than others. When an innovation disrupts the mainstream technology or Continue Reading » (more)

Podcast: The upcoming tcworld India conference on March 12-13, with Akash Dubey

Mon, 02/09/2015 - 04:48
Length: 25 min. Download MP3 (right-click and select Save As) This weekend I talked with Akash Dubey, one of the main organizers of the tcworld India conference, about the upcoming conference in India. Although I haven’t mentioned it on my blog yet, this year I’m actually attending tcworld India as an invited keynote presenter. tcworld Continue Reading » (more)

Why do we need PDFs?

Thu, 02/05/2015 - 10:09
I’ve never been a fan of PDFs, but PDF output is usually a requirement someone invariably brings up for documentation. In some cases, often for unstated reasons, users will ask for a PDF, and product managers expect technical writers to deliver one. When I get these requests, I usually create a zip file of the Continue Reading » (more)

Upcoming workshop: Creating Interactive Video Tutorials, with Bernard Aschwanden on Feb 21

Thu, 02/05/2015 - 09:49
If you’re in the San Francisco Bay area and are interested in learning how to create interactive video tutorials, we have a workshop just for you. The STC Silicon Valley chapter is hosting a workshop titled Best Practices when Creating Interactive Video Tutorials. The workshop is led by Bernard Aschwanden — a consultant at Publishing Continue Reading » (more)

Best practices for API documentation — podcast with Andrya Feinberg

Wed, 02/04/2015 - 11:43
I recently talked with Andrya Feinberg, a documentation manager and content strategist for Emotient, about best practices with API documentation. Below the recording is a writeup Andrya has provided that summarizes some of the points she makes in the podcast. Length: 42 min. Download MP3 (right-click and select Save As) Andrya also wrote up a Continue Reading » (more)

Creating context-sensitive help by converting your help into a JSON API with Jekyll

Mon, 02/02/2015 - 02:18
I’ve written a lot about documenting APIs, but what if your documentation itself could function as an API? By this I mean, what if you could give developers an endpoint through which they could retrieve different parts of your documentation? This setup would work well for context-sensitive help within an application. I stumbled across a Continue Reading » (more)

Upcoming webinar: Survival strategies for API documentation

Sun, 02/01/2015 - 17:19
I’m giving a webinar to the Southern Ontario STC this Monday, Feb 2, at 4pm PST (7pm EST). Here’s the topic: Survival strategies for API documentation If you’re documenting an API for the first time, you may be in survival mode just trying to decipher the code, unravel developer speak, and publish a coherent set Continue Reading » (more)

Writing is like sorting laundry — practical advice for tackling documentation projects

Thu, 01/29/2015 - 15:51
A reader recently asked, This is sort of a beginner question, although I am not technically a beginner. I’ve been helping to maintain a medium sized doc set for a suite of products at a large company for over ten years. I’ve never written a significant document from scratch in my 10+ years as a Continue Reading » (more)

10 reasons for moving away from DITA

Wed, 01/28/2015 - 15:36
Several people have asked me why I’m moving away from DITA. During my API workshop at TC Camp, near the end, one experienced DITA person said, What couldn’t you do with DITA in publishing API documentation? Another reader recently said, I’m curious to know why you’re moving away from DITA, since we’re thinking about adopting Continue Reading » (more)

API workshop video + audio + slides + workshop files from TC Camp

Tue, 01/27/2015 - 16:01
I recently gave an API workshop at the TC Camp Unconference last weekend in Santa Clara, California. This post includes a video recording of my presentation, along with slides, audio, and workshop files. I actually prepared four separate slide decks for the workshop, but only used 2 and a half of them. I don’t know Continue Reading » (more)