You are here

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 feed
Updated: 33 min 29 sec ago

Proposals for 2016 *STC Silicon Valley Chapter* presentations now accepted

Thu, 08/27/2015 - 03:00

Are you interested in presenting to the Silicon Valley STC Chapter this year? We're now accepting proposals for 2016 speakers.

What presenting involves

Presenting to the STC Silicon Valley Chapter (located in the South Bay of the San Francisco, California) involves the following:

  • Preparing a 1-hour presentation relevant to technical writers
  • Preparing some slides or other visuals to accompany your presentation
  • Creating a short description of yo (more)

My process for creating vector diagrams with Illustrator

Sun, 08/23/2015 - 03:00
Create the file in Adobe Illustrator

Adobe Illustrator is my preference for diagrams, conceptual workflows, or any other graphic that's not a screenshot. This is because Illustrator creates vector graphics, whereas other applications (e.g., Snagit, Photoshop) create raster graphics.

Vector graphics are actually XML files that are mathematically drawn, whereas raster graphics are pixel-based images (little dots). Raster graphics look good at the dimensions you create them at but get fuzzy if you resize them. In contrast, vector graphics look sharp at any resolution, so they' (more)

Version 3.0 of my Documentation theme for Jekyll released

Thu, 08/13/2015 - 03:00
Version 3.0 released

Version 3.0 of my Documentation theme for Jekyll is now available. You can download the source code from the theme's Github repo.

To see an example of the single sourced outputs, see the following:

The Designers output has det (more)

Version 3.0 of my Documentation theme for Jekyll released

Thu, 08/13/2015 - 03:00
Version 3.0 released

Version 3.0 of my Documentation theme for Jekyll is now available. You can download the source code from the theme's Github repo.

To see an example of the single sourced outputs, see the following:

The Designers output has det (more)

Question: What qualities should technical writers have to work at startups?

Wed, 08/12/2015 - 03:00
Question from recruiter

A recruiter recently asked me what traits technical writers should have for startup companies. Startup environments post unique challenges when it comes to technical writing. Here are a few thoughts about the characteristics technical writers need to succeed in this environment.

1. Technical aptitude

You need to be strong enough technically to select and implement the appropriate tools for the technical writing tasks. At a startup company, you will likely need to decide on the authoring and publishing tools and workflow, get support to make purchases, and t (more)

Podcast: The divide between academics and practitioners — Interview with Lisa Meloncon

Mon, 08/10/2015 - 03:00

Here's the audio for the podcast:

You can download the MP3 file here.

Podcast summary

One common response I usually get with podcasts is that people want a transcript of the audio. Although I don't have time to make a verbatim transcript, I decided to write out a brief summary of notes and highlights (based on what jumped out at me during my own listening) in a more informal way this time. Here (more)

Why is there a divide between academics and practitioners in tech comm?

Wed, 08/05/2015 - 03:00
The divide between practitioners and academics

TechCommGeekMom recently attended IEEE ProComm in Ireland and wrote an interesting post highlighting the divide that exists between practitioners and academics.

I've been interested in this divide for some time. In some regards, bloggers and academicians have some somewhat similar goals. Both groups desire to increase their learning. Bloggers write about their experiences, share what they' (more)

When are wikis ever successful?

Thu, 07/30/2015 - 03:00
What went wrong with the wiki model

The other day I had an email exchange with someone about wikis and scenarios where wikis might work well. I haven't talked much about wikis on my blog lately. But a few years ago, when I working in Utah in a community environment with a lot of contributors, I did use Mediawiki for a couple of years. In some ways the wiki worked well, and in other ways it did not.

The main problem was that wikis allow anyone to contribute junk content with no responsibility to maintain it. As a result, wikis quickly turn into content dumpyards (full of redund (more)

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

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.


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) 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 The first course available is "Introduction to DITA." 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.src=["https:"===location.protocol?"https://":"http://",""].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.


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)