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

API technical writing course on Udemy, from Peter Gruenbaum, and some thoughts on documenting JSON

Fri, 05/22/2015 - 10:12
Peter Gruenbaum’s API technical writing course on Udemy is an excellent starting point for learning API documentation. He explores one of the more difficult parts of API documentation, which is describing JSON and XML data structures (usually in responses). Finally, a course on API doc One of the frequent questions people ask me is where Continue Reading » (more)

Switched commenting systems to Disqus

Sun, 05/17/2015 - 14:35
Just a heads up, with comments on my blog, I’m now using Disqus as opposed to the native commenting system in WordPress. This means you’ll need to log in using one of the four methods provided by Disqus (Google, Twitter, Facebook, or Disqus) to leave a comment. Why did I switch from WordPress’ native comments Continue Reading » (more)

API Documentation presentation to East Bay STC chapter — slides and recording

Sat, 05/16/2015 - 18:10
The other week I gave a presentation on API documentation to the East Bay STC chapter. Here are the slides and recording. API Documentation presentation to East Bay STC Chapter from Tom Johnson Here’s the PowerPoint version of the slides. Here’s the MP3 audio file: Links to more information This presentation is similar to other Continue Reading » (more)

Introduction to technical writing — slides and audio recording

Sat, 05/16/2015 - 16:58
A few weeks ago I gave a presentation to a small group of beginning technical writers in India. The presentation was a 20 minute introduction to technical writing, and I gave the presentation over Skype. Slides Here are the slides: Audio recording Here’s the MP3 audio file: Links to more information This presentation is similar Continue Reading » (more)

How to design documentation for non-linear reading behavior

Fri, 05/15/2015 - 08:18
To account for non-sequential reading behavior, provide your readers with sufficient context to orient themselves with your topic. This is the third post in my series about user-centered documentation. First observations about non-sequential reading In the late 1980s, John Carroll observed non-sequential reading behavior with how people consumed documentation in his seminal book, The Nurnberg Continue Reading » (more)

Recording and slides from “Jekyll vs. DITA: Bridging the Gap Between Tech Comm and the Web” presentation

Fri, 05/15/2015 - 01:19
Yesterday I gave a presentation to STC Berkeley about ways to bridge the gap between tech comm tools and web development tools. After talking about innovation patterns, I focused on static site generators, specifically Jekyll. I also explained how DITA compares to Jekyll. Slides Here are the slides: Audio recording Here’s the MP3 audio file: Continue Reading » (more)

User-centered documentation slides

Thu, 05/14/2015 - 09:51
This is a post in my on-going series on user-centered documentation. I usually write a series of posts, and then create a slide presentation summarizing my insights at the end. Then I usually give the presentation at some venue. Well, I didn’t have time to write out the posts before giving the presentation this time, Continue Reading » (more)

Upcoming presentation: Jekyll versus DITA: Bridging the Gap between Tech Comm and the Web

Sun, 05/10/2015 - 09:55
If you’re in the San Francisco Bay area (near Oakland, actually), you might be interested in an upcoming presentation I’m giving to the STC Berkeley chapter this Wednesday. Details are on the STC Berkeley chapter site. I also included the description below: Jekyll versus DITA: Bridging the Gap between Tech Comm and the Web Although Continue Reading » (more)

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)