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: 54 min 59 sec ago

Variables and conditional processing in Jekyll versus DITA

Fri, 03/27/2015 - 01:34
In the previous post, I compared writing in Markdown versus writing in XML. In this post, I want to look at variables and conditional processing between the two platforms. Variables in Jekyll In Jekyll, you can assign a variable a specific value, like this: Now you can use {{dog_name}} in your content and it will Continue Reading » (more)

Misconception: Markdown is more limiting than DITA (Jekyll versus DITA)

Fri, 03/27/2015 - 01:22
In my previous post, I noted a new series in which I plan to compare Jekyll against DITA. In this first post, I want to debunk the myth that Markdown formats with static site generators like Jekyll are more limiting than DITA. This is a point discussed in the Content Content podcast that I referenced Continue Reading » (more)

Check out Ed Marsh’s podcast, and also My New series: Jekyll versus DITA

Tue, 03/24/2015 - 02:34
In case you haven’t already discovered it, there’s a great new podcast in the tech comm field called Content Content, by Ed Marsh. So far Ed has recorded two episodes, each about an hour long. Ed follows an easy-going interview format, and he does an excellent job in bringing out the best in his show’s Continue Reading » (more)

Some thoughts on attending tcworld India 2015

Mon, 03/23/2015 - 02:00
I just spent the last week in Bangalore, India. The tcworld India 2015 conference took place on a Thursday and Friday, and I spent Saturday and Sunday exploring the city. This was an eye-opening trip for a number of reasons, and I wanted to capture some of my thoughts and experiences here and share them Continue Reading » (more)

PDF still trumps browser-based help?

Thu, 03/19/2015 - 22:57
In the Skills and Technology Survey 2014 by WritersUA, it appears that PDF manuals are the most common deliverable: Support for manuals in the form of PDF (77%) is at the top of the list as the most valued technology component. Using PDF as a delivery format has become a staple in our documentation sets. Continue Reading » (more)

Recording of API documentation workshop (REST and Javadoc) at tcworld India 2015

Thu, 03/19/2015 - 21:26
Here’s a recording of the API documentation workshop that I gave at tcworld India 2015: In this workshop, I cover the following: Overview of API documentation Deep Dive into REST API documentation Deep Dive into Javadoc API documentation This is similar to other presentations I’ve given on API documentation, except that in this workshop, I Continue Reading » (more)

Recording of Innovation in Technical Communication keynote at tcworld India 2015

Wed, 03/18/2015 - 15:35
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 Continue Reading » (more)

Slides for tcworld India 2015 presentations

Wed, 03/11/2015 - 14:43
I have the opportunity of attending the tcworld India 2015 conference this week in Bangalore. I’m giving a keynote presentation on the topic of innovation and a workshop on API documentation. I posted my slides here in case you’re interested: Innovation in technical communication API documentation workshop Notes about the slides As I mentioned in Continue Reading » (more)

Reveal JS: An HTML5 alternative to PowerPoint, with support for SVG graphics

Wed, 03/11/2015 - 14:31
In trying to find a slide format that supported SVG image formats, I was exploring some PowerPoint alternatives and stumbled across Reveal JS. I like Reveal JS so much, I do not think I will ever use PowerPoint again. Here’s the slide show I put together with Reveal JS: Innovation in Technical Communication. Press F Continue Reading » (more)

Pushing content into any format with Jekyll

Fri, 03/06/2015 - 11:18
In the previous post, I talked about help APIs as a way to deliver help inside applications. In this post, I’ll explain how to push your help content into any format. Let’s say that you have three different channels where you want to push your help content. Channel one is an S3 bucket in Amazon Continue Reading » (more)

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)