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

Three questions people ask me each week

Wed, 07/01/2015 - 03:00
Question 1

The first question goes something like this:

Hi Tom, I found your blog and really like the content. I'm currently a ________ with a degree in ____. I've been working for the past few years doing __. However, I really dislike my job. I realized that it involves ____ and _________ all day long.

I'm thinking of transitioning into a technical writing career. I like to write, and I scored high grades in all my writing classes. Can you give me any advice? How can I get a job in technical writing? Is there a particular city where there are lots of technica (more)

Slides, notes, and lessons learned at the STC Summit 2015 in Columbus, Ohio

Mon, 06/29/2015 - 03:00
Slide presentations

Here are the slides from my workshop on REST API documentation. I have two sets of slides:

Documenting REST APIs from Tom Johnson

For detailed notes, see Documenting REST APIs.

Publishing (more)

My upcoming workshop and presentation at the STC Summit 2015 in Columbus, Ohio

Thu, 06/18/2015 - 03:00
Upcoming API documentation workshop

I'm giving a 3.5 hour workshop on API documentation at the STC Summit in Columbus this year. Although I gave some workshops and presentations on APIs earlier this year, for this Summit workshop, I've completely reworked the material and focused almost entirely on REST APIs. I'm really excited about the content I've got in this workshop and hope to repurpose it later with an online learning platform.

The API documentationworkshop is Saturday from 1:00pm to 4:30pm at the Hyatt Regency in Columbus. For details, see (more)

How to avoid early death from sitting down all day

Thu, 06/18/2015 - 03:00

I'm growing increasingly nervous by the number of studies that show how sitting down all day poses health risks equivalent to smoking a pack a day. Just google sitting all day is the equivalent to smoking and you'll find plenty of articles.

I decided to download Break Time from the App store.

So far it works pretty well. (more)

How do you authenticate your documentation?

Wed, 06/17/2015 - 03:00
Why authenticate documentation?

As a blogger, I'm not in favor of authenticating anything. But most companies I've worked for have required users to authenticate with a username and password in order to access the documentation I write. I'm currently trying to find a good solution for authenticating my documentation, and I could use a few tips if you have information to share.

The traditional solution for authenticating documentation

The traditional solution for authenticating documentation is to load it onto the same server as the application. The authentication is th (more)

My daughter published a real video game through "Girls Make Games" camp

Wed, 06/17/2015 - 03:00

Girls Make Games is a camp devoted to teaching girls from grade school through high school how to make games on computers. This short video shows the purpose behind the Girls Make Games camp:

Instead of taking games away from kids, the camp tries to channel the girls' interest and energy into creating games themselves. The girls learn programming, game design, game mechanics, and other aspects of creating a real game.

Where to Register

Girls Make Games has camps all over the globe this year. You can see a (more)

Check out my conversation on ContentHug

Wed, 06/17/2015 - 03:00

Vinish Garg has a series of "conversations" going on his site, Contenthug. Today he posted a conversation he had with me.

The conversations are short, interactive Q&A, mostly about content strategy and organizational challenges that relate to tech comm.

Contenthug.com itself i (more)

How can technical writers cut through engineering jargon and decode complex information?

Mon, 06/08/2015 - 03:00
A typical tech comm scenario

The other day I was asked to update documentation for the latest release. The team pointed me to some wiki pages that described the new features. As I looked through the pages, they were full of engineering speak as thick as it gets, with Java methods, acronyms, almost no explanation of the context or "why" behind the feature, and other technical blah blah blah.

After 5 minutes, I browsed to another tab and looked for something else to do. I didn't want to deal with figuring all of that out right then. Soon I came back to the jargon-filled (more)

Why no one stopped by my technical writing booth at career fair day

Sun, 05/31/2015 - 03:00
Technical writing booth at Career Fair day

The other week I volunteered at a career fair at my daughter's school. My oldest daughter is in 8th grade, and there were about 300 students who visited the various career booths in a gymnasium.

I had high hopes in stimulating students' minds toward a career in technical writing. It became clear after the first 20 minutes, however, that technical writing was far from the interest of most students.

In fact, during the 2 hour career fair, only about 10 students stopped by my booth. Most of them weren't specifically inte (more)

Moved my blog from WordPress to Jekyll

Fri, 05/29/2015 - 03:00

After experimenting with Jekyll as a documentation platform for the past several months, I decided to migrate my blog from WordPress to Jekyll.

Although I think WordPress is a nearly perfect blogging platform, and I have extensive knowledge about building sites in WordPress, I still made the switch.

Here are some reasons why I switched:

Tired of the split world view

My main reason for switching probably differs from the most common reasons people switch from WordPress to Jekyll. I think that the publishing platforms we use to create technical documenta (more)

Integrating Documentation into engineering code and workflows

Tue, 05/26/2015 - 03:00
Write the Docs video

If you work with developer documentation, definitely check out Riona Macnamara's Write the Docs 2015 presentation: Documentation, Disrupted: How two technical writers changed Google engineering culture.

The problem: Scattered documentation

Riona Macnamara is a technical writer at Google. Riona says that several years ago, internal documentation at Google was scattered across wikis, Google Sites, Google Docs, and other places.

In surveys at Google about the workplace, many employees said t (more)

Integrating Documentation into engineering code and workflows

Mon, 05/25/2015 - 20:00
Write the Docs video

If you work with developer documentation, definitely check out Riona Macnamara's Write the Docs 2015 presentation:Documentation, Disrupted: How two technical writers changed Google engineering culture.

The problem: Scattered documentation

Riona Macnamara is a technical writer at Google. Riona says that several years ago, internal documentation at Google was scattered across wikis, Google Sites, Google Docs, and other places.

In surveys at Google about the workplace, many employees said th (more)

Integrating Documentation into engineering code and workflows

Mon, 05/25/2015 - 20:00
Write the Docs video

If you work with developer documentation, definitely check out Riona Macnamara's Write the Docs 2015 presentation:Documentation, Disrupted: How two technical writers changed Google engineering culture.

The problem: Scattered documentation

Riona Macnamara is a technical writer at Google. Riona says that several years ago, internal documentation at Google was scattered across wikis, Google Sites, Google Docs, and other places.

In surveys at Google about the workplace, many employees said th (more)

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

Fri, 05/22/2015 - 10:12
Finally, a course on API doc

One of the frequent questions people ask me is where to get more training on API documentation. A few months ago, I published a podcast with Peter Gruenbaum on automating REST API documentation. Peter has recently published a course on Udemy called Learn API Technical Writing: JSON and XML for Writers.

I highly recommend the course as a starting poi (more)

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

Fri, 05/22/2015 - 10:12
Finally, a course on API doc

One of the frequent questions people ask me is where to get more training on API documentation. A few months ago, I published a podcast with Peter Gruenbaum on automating REST API documentation. Peter has recently published a course on Udemy called Learn API Technical Writing: JSON and XML for Writers.

I highly recommend the course as a starting poi (more)

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 to Disqus? Several reasons:

  • Too much spam gets past Akismet. For every real comment, I have to delete about 10 spam comments.
  • I'll probably migrate this blog to Jekyll, in which case I'll need a third-party service to handle comments.
  • Disqus' comme (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 to Disqus? Several reasons:

  • Too much spam gets past Akismet. For every real comment, I have to delete about 10 spam comments.
  • I'll probably migrate this blog to Jekyll, in which case I'll need a third-party service to handle comments.
  • Disqus' comme (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 sl (more)