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

An easy way to support my site: Sign up for technical writing job alerts

Thu, 07/30/2015 - 03:00

I've added a Zip Recruiter feature on my site. You can now search for jobs by clicking the Jobs button on the top navigation bar. Additionally, you can sign up for job alerts by filling out the form at the bottom of each post.

Here's what's cool about this feature. Not only are the jobs automatically filtered to your area, when you get email updates about the jobs that match your search, the job email notifications will actually come from tom@idratherbewriting.com.

Of course each time you click a job link through my (more)

Podcast: How do design, length, and relevance affect how people use API reference docs — interview with Bob Watson

Thu, 07/30/2015 - 03:00
Listen to the podcast

You can download the MP3 file here.

Summary

Bob was a software engineer for 17+ years. He decided to get a PhD from the University of Washington's Human Centered Design and Engineering because he felt that if the documentation for his software were better, the adoption of the software would increase. This led him to pursue research in technical (more)

LearningDITA.com: A new online learning resource for DITA by Scriptorium

Tue, 07/28/2015 - 03:00
A Free Course on DITA

One common question I receive from people on this site is how they can learn DITA. Scriptorium has published a new online course (their first, I think) called LearningDITA.com. The first course available is "Introduction to DITA."

Learningdita.com is a free online resource created by Scriptorium for learning DITA About the course

The course is well-organized and oriented for beginners. Here are some general characteristics of t (more)

Peter Gruenbaum has released part 2 of his Udemy course on API technical writing

Fri, 07/24/2015 - 03:00
Part 2 is now available

Peter Gruenbaum has released part 2 of his Udemy course on API technical writing. Whereas part 1 focused mostly on requests and responses from REST APIs, part 2 gets into a lot more detail with REST APIs and provides more depth. (Part 2 felt more substantial to me than part 1, but it depends your familiarity with JSON and XML.)

In part 2, Peter dives into headers, a (more)

Survey results about the REST API workshop

Fri, 07/24/2015 - 03:00
Survey results

Earlier this week I asked for your feedback about a possible REST API workshop I was thinking about providing. If you would like to view the answers from the survey, you can read them here or from the screenshot below.

In summary, it seems that there is a substantial interest in a REST API workshop (particularly on a Saturday morning or w (more)

Is it harmful to frequently switch contexts among multiple projects?

Thu, 07/23/2015 - 03:00
Juggling multiple projects is the norm

It seems that nearly every job description for technical writing mentions that the writer will need to "juggle multiple projects." And it's true. The nature of technical writing is that you are rarely dedicated to a single project. Most of the time, you are only needed near release times, so you end up switching among multiple projects depending upon which project needs documentation the most.

For example, right now I'm documenting three separate products. Usually their release cycles don't all crest at the same time, so (more)

Survey about possible REST API workshop — your feedback would be helpful

Mon, 07/20/2015 - 03:00

I'm thinking of giving an in-person workshop on REST APIs in Mountain View, California, and I'd like to get some general feedback about how this workshop should be designed. Can you answer these simple survey questions?

(function(t,e,c,n){var o,s,i;t.SMCX=t.SMCX||[],e.getElementById(n)||(o=e.getElementsByTagName(c),s=o[o.length-1],i=e.createElement(c),i.type="text/javascript",i.async=!0,i.id=n,i.src=["https:"===location.protocol?"https://":"http://","widget.surveymonkey.com/collect/website/js/MOkTi1x0WrvzOU7QLcqyn0vALa5mMh4SiOIcB1k59ENC2uymyEWReu05_2BtFokHcg.js"].join(""),s.parentN (more)

Getting mobile friendly display and responsive design just right, especially with ads

Fri, 07/17/2015 - 03:00
Mobile friendly displays now a requirement, not an extra

It used to be that having a responsive display for your mobile site was a nice-to-have feature. However, now Google will actually penalize you in the search results if your site isn't mobile friendly. According to TNW News,

This is one of the biggest changes to the Google algorithm in years, so it’s one to take seriously. From yesterday, a site’s “mobile friendliness” will now play a key role in the way it is ranked, and sites that are not mobile optimised will appear lower down on Google’s search pages.

(more)

Reader question: How do I move forward out of a stagnant tech writing career?

Wed, 07/15/2015 - 03:00

I recently received the following question:

Hi Tom,

I'm an avid reader of your blog and I'm writing to seek your advise on improving my stagnant career.

I'm a Technical Writer working in New York City, working for a financial services consulting firm. I'm a computer science graduate and I chose technical writing as I loved writing more than programming.

In my short career spanning a little less than 5 years, I've documented many web-based and windows-based software applications and learned quite a few authoring tools like Adobe Framemaker, Adobe Robohelp, et (more)

Build a technical writing portfolio by writing documentation for startups

Fri, 07/10/2015 - 03:00

If you need to build your technical writing portfolio with sample documentation, you have several options:

  • Write documentation about products you know and own.
  • Write documentation for open source projects.
  • Write documentation for statups who don't have official technical writers.

This last option is one I haven't highlighted on my blog, but it may actually be the best option. Usually startups don't hire technical writers until their product is mature enough to bring to market. At that time, they usually have a sizable amount of docu (more)

Guest post: 10 New Things to Love and Hate About Flare

Thu, 07/09/2015 - 03:00
table tr td.check img { padding-top:5px; }

The following is a guest review by Karen Rempel, a technical writer based in New York and Vancouver.

It's been over seven years since Tom wrote his review of MadCap Flare v3. Over the years, hundreds of writers and potential Flare users have consulted his review to decide whether Flare will suit their needs.

Flare is up to v11 now, and I recently embarked on a robus (more)

Should QA test documentation?

Thu, 07/09/2015 - 03:00

In my previous post, The key to writing good documentation: Testing your instructions, I noted that although quality assurance teams can review documentation, my experience is that they review it like a robot. They don't comment qualitatively, noting whether something is clear or not, whether the message is on target, whether the tasks represent the user's workflow and business needs. Instead, they analyze the steps strictly for accuracy (which does have benefits, of course).

However, I'm st (more)

Listen to Ed Marsh's Content Content podcast with me as a guest

Wed, 07/08/2015 - 03:00

If you like podcasts, check out episode 4 of Ed Marsh's Content Content podcast. Ed talks with me at length about a variety of tech comm topics — everything from how I got into technical writing to publishing tools, DITA, Jekyll, Markdown, and more.

Chatting with Ed made me remember how much I like both listening to and recording podcasts. (more)

Pingdom reports with WordPress on Bluehost/MaxCDN versus with Jekyll on Github

Wed, 07/08/2015 - 03:00
Pingdom reports

Pingdom is a service that checks your website for performance, measuring download speed, outages, and more. For free, you can configure Pingdom to periodically check your site and let you know when it's down.

Pingdom reports with WordPress on Bluehost with MaxCDN

When my blog was on WordPress, hosted on Bluehost and using MaxCDN (a CDN network), here were the average response times:

Pingdom reports with Jekyll on Github (no MaxCDN)

After moving my blog to Jekyll and hosting on Github, here are the average (more)

Listen to Ed Marsh's Content Content podcast with me as a guest

Wed, 07/08/2015 - 03:00

If you like podcasts, check out episode 4 of Ed Marsh's Content Content podcast. Ed talks with me at length about a variety of tech comm topics — everything from how I got into technical writing to publishing tools, DITA, Jekyll, Markdown, and more.

Chatting with Ed made me remember how much I like both listening to and recording podcasts. (more)

Pingdom reports with WordPress on Bluehost/MaxCDN versus with Jekyll on Github

Tue, 07/07/2015 - 03:00

Pingdom is a service that checks your website for performance, measuring download speed, outages, and more. For free, you can configure Pingdom to periodically check your site and let you know when it's down.

When my blog was on WordPress, hosted on Bluehost and using MaxCDN (a CDN network), here were the average response times:

After moving my blog to Jekyll and hosting on Github, here are the average response times:

I could integrate MaxCDN with Jekyll, but I'm not sure if there would be much benefit, (more)