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: 2 hours 31 min ago

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)

Reinventing the table of contents

Mon, 01/26/2015 - 15:44
I’ve been exploring different ways to create a table of contents (TOC). Traditionally, user guides have a long TOC in the left column of each page. This works all right when you have about 50 pages, but when you scale up the doc set to 500 pages, the TOC becomes a bulky, unusable mess. For Continue Reading » (more)

Implementing ScrollSpy with Jekyll to auto-build a table of contents

Tue, 01/20/2015 - 15:41
I mentioned in a post last week that I’m experimenting with a Jekyll prototype for technical documentation. I stumbled upon one of the coolest and most interesting topics a few days ago while integrating “ScrollSpy” on Jekyll. ScrollSpy is a dynamic feature that “spys” on the headings as you scroll past them and dynamically highlights Continue Reading » (more)

Moving from passive to reactive documentation — recording of presentation by Greg Koberger, ReadMe.io founder

Mon, 01/19/2015 - 10:51
The following is a recording of a presentation about passive versus reactive documentation by Greg Koberger, developer and designer for ReadMe.io, a slick new REST API documentation tool. Greg gave this presentation at the STC Silicon Valley chapter meeting on January 12, 2015 in Santa Clara, California. (He gave a similar presentation to a Write Continue Reading » (more)

Most important factor in APIs is complete and accurate documentation

Thu, 01/15/2015 - 10:20
A 2013 survey by Programmable Web that included about 250 respondents found that complete and accurate documentation was the most important factor in an API: This is certainly an encouraging finding for technical writers, and suggests that more attention and focus should be given to documentation. I think I’m going to print this picture out Continue Reading » (more)

API doc survey: Do engineers write API doc in the source code?

Thu, 01/15/2015 - 10:08
Another question in my API doc survey was as follows: Do engineers write the initial API documentation in the source code (e.g., Javadoc syntax)? 42 people responded. The results are as follows: This question was a little problematic. Because a lot of tech writers are working on REST APIs, a lot of developers don’t write reference Continue Reading » (more)

API doc survey: How much of your doc process is automated?

Thu, 01/15/2015 - 09:02
This question in my API doc survey was so poorly worded that the answers are mostly confusing. Unfortunately, this was the first question in the survey and probably the most vague. Here’s the question: Do you generate Javadoc or Doxygen files manually, or are they auto-rendered as part of the build process? REST API documentation Continue Reading » (more)

Several REST API tutorials using the EventBrite, Klout, and Flickr APIs

Wed, 01/14/2015 - 10:28
In preparation for my upcoming API workshop at TC Camp1, I created several REST API tutorials. These tutorials walk through the process of calling and endpoint and displaying parts of the response on a web page. Here are the tutorials: EventBrite example Klout score example Klout influenceez example Flickr example If you feel like walking Continue Reading » (more)

Experimenting with Jekyll for tech comm

Wed, 01/14/2015 - 03:15
Today I had the opportunity to explore Jekyll a bit more. Jekyll is a static site generator that helps you build websites quickly. The sites can be blog sites or regular sites (or documentation sites). However they’re used, there’s definitely a trend toward static site generators over database-driven sites. Five years ago, online CMS platforms Continue Reading » (more)

API doc survey: Most challenging aspect of API documentation

Mon, 01/12/2015 - 15:58
In my API documentation survey, one of the questions I asked was the following: What aspect of API doc do you find most challenging (e.g., understanding code)? This turned out to be a great question. Because the responses were open-ended, I didn’t force respondents to select from a pre-existing list. Instead, they could write whatever they Continue Reading » (more)

Jan 12 Silicon Valley STC meeting: Passive vs. reactive doc + readme.io

Mon, 01/12/2015 - 00:13
If you’re in the San Francisco Bay area (near Santa Clara), come join us Monday, January 12 at around 7pm for a presentation by Greg Koberger on passive versus reactive documentation, plus a demo of readme.io docs, which is a new cloud platform for REST API documentation that is extremely well-designed. I saw Greg present Continue Reading » (more)

Question: How do I add my DITA content in Confluence for SME review?

Fri, 01/09/2015 - 10:20
Someone recently asked me: I am using DITA with structured Frame and Tech Comm Suite. Do you know the best output to use so the docs can be displayed in Confluence? The SMEs want to proofread in Confluence and use it for a knowledge base. Ideally, I’d like to output from DITA or Robohelp and Continue Reading » (more)

Podcast: Unifying the API doc publishing toolchain, with Mark Baker

Thu, 01/08/2015 - 10:12
Length: 62 min. Download MP3 (right-click and select Save As) In this podcast, I talk with Mark Baker from Every Page Is Page One about unifying the API doc publishing toolchain. Here are some questions I ask Mark during the podcast: What kinds of API docs pose challenges with the tool chain? Do API reference Continue Reading » (more)

API doc survey result: How to learn what you need to know?

Wed, 01/07/2015 - 02:26
In my API doc survey, one of the questions I asked was the following: How did you learn what you needed to know (e.g., Lynda.com, Safaribooksonline)? 41 people responded. The results look like this: Once again, all answers are freeform, so I grouped similar answers into like categories. For “self-taught,” people wrote things like trial Continue Reading » (more)

API doc survey result: How do you get the source files that contain code comments?

Wed, 01/07/2015 - 01:58
In my API doc survey, one of the questions was the following: How do you get the source files containing code comments? (e.g., Git, Mercurial)? Out of 42 responses, here are the results: This question partly served as a check to an earlier question, Do you create documentation by looking at the source code of Continue Reading » (more)

Podcast: Automating REST API documentation, with Peter Gruenbaum

Tue, 01/06/2015 - 02:07

Length: 40 min.

Download MP3 (right-click and select Save As)

In this podcast, Peter Gruenbaum talks about automating REST API documentation. Here are a few questions I asked Peter during the podcast:

  • What do people mean when they use the term “automated documentation”?
  • Is automated documentation preferable to manual documentation?
  • Why is it more difficult to automate REST API documentation than it is with plat (more)

New cost-per-click feature for advertising on I’d Rather Be Writing During 2015

Tue, 01/06/2015 - 00:28

I usually renew advertising on I’d Rather Be Writing at the beginning of the year. I just updated my Advertising page with more details. This year I’m hoping to try something new. In the past, I’ve only done advertising based on the number of impressions. That is, each time my site loads, an ad appears and makes an impression for the year. Over the course of 2014, there were about 588,000 impressions (I equate each page load with one impression).

This year, however, I’m adding the number of clicks as an a (more)

My *real* top 10 technical writing trend predictions for 2015

Mon, 01/05/2015 - 11:00

On New Years day I posted a spoof of trends because I think trends posts get to be a bit ridiculous. During this time it’s like the Mardi-Gras of free and wild speculations.

However, I did receive some great comments on the post. One of my favorites was this one:

Wow and Wow. At age 76, as a recently minted Journalism major, with a minor in geomorphology, an (more)

Top 10 posts, podcasts, tweets of 2014 — and what it all means

Mon, 01/05/2015 - 10:51

Here’s a look at the top 10 posts, podcasts, and tweets published in 2014 on I’d Rather Be Writing. After the lists, I explain my takeaways from looking at the metrics.

Top 10 posts written in 2014

Based on Google Analytics, these 10 posts written in 2014 received the most traffic:

  1. A simple way to write, edit, and publish documentation online using Google Docs and Markdown
  2. (more)