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 22 min ago

Technical writing internship in San Jose, California for summer 2015

Fri, 05/01/2015 - 01:42
If you’re a student interested in a technical writing internship that involves working at 41st Parameter/Experian in San Jose (working closely with me), then check out the posting here. Here’s the description: The Summer Internship Program gives students an opportunity to work at Experian’s Global Fraud & ID organization. Running from late May to August, Continue Reading » (more)

New series: User-centered documentation

Fri, 04/24/2015 - 01:40
I’m starting a new series on my blog about user-centered documentation. If you’re new to my blog, a series is a collection of posts (usually about 10) focused on the same topic. The series format gives me a chance to explore a topic in depth without publishing a monolithic post all at once. Origins of Continue Reading » (more)

Final analysis between DITA and Jekyll

Wed, 04/15/2015 - 16:17
As the ninth post in this series, I think I’m wrapping it up. This post will contain my final analysis comparing Jekyll with DITA. During this series, I had the misfortune of cutting a tendon in my thumb with a box cutter knife, and so typing has been difficult. I’ve had to wear a cast Continue Reading » (more)

Producing PDFs in DITA versus Jekyll

Wed, 04/15/2015 - 01:17
In this near final post in my series comparing DITA with Jekyll, I want to explore contrasting ways to produce PDFs. I have other blog posts where I have stated how much I dislike PDFs with technical documentation. The main problem is that even though PDFs go out of date quickly, users hang onto them Continue Reading » (more)

Reviewing content in DITA versus Jekyll

Tue, 04/14/2015 - 00:18
This is another post in my series comparing DITA against Jekyll. In this post, I want to compare reviewing methods for the two systems. Theoretically, you could review content from both systems in the same way. But you could also take very different approaches to reviewing content as well. How to review content in Jekyll Continue Reading » (more)

Creating links in DITA versus Jekyll

Tue, 04/07/2015 - 00:08
In this ongoing series, I’m comparing tech comm techniques with DITA versus Jekyll, a popular static site generator. How you create links is more than a simple technical detail. Linking is one of the main strategies for connecting and interrelating information. How to create links in DITA In DITA, you have several choices for making Continue Reading » (more)

Newbie to Technical Writer in 4 Easy Steps

Fri, 04/03/2015 - 15:49
The following is a guest post from Kaylin Tristano, a new technical writer in the medical software industry. In this post, she shares her tips for transitioning into the field of technical writing. I landed my first technical writing job about four months ago. I’d been working as a librarian and had no writing experience Continue Reading » (more)

Building a table of contents with DITA versus Jekyll

Fri, 04/03/2015 - 01:37
In my ongoing series comparing Jekyll against DITA, I want to touch on how you construct a table of contents. Creating a TOC with DITA The ditamap file in DITA is arguably the most important file in a DITA project, and it has a lot of features. Basically, the ditamap defines the table of contents Continue Reading » (more)

Creating re-usable chunks (conref) in Jekyll versus DITA

Wed, 04/01/2015 - 11:45
In my previous post, I explained how to do variables and conditional processing in Jekyll. One of the commenters wondered about how you create “intelligent content” with Jekyll: how does a Jekyll (or similar) approach let us create intelligent content? There was a recent conference in San Francisco focused on intelligent content, and one of Continue Reading » (more)

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)