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: 4 min 12 sec ago

Learning how developers think, and other API doc insights: Podcast with Joe Malin

3 hours 20 min ago

Length: 45 min.

Download MP3 (right-click and select Save As)

In this podcast, I talk with Joe Malin about a variety of topics within API documentation, including how developers think, best practices, and more. Joe is a former software engineer who turned to technical writing many years ago. He has worked at a variety of companies in API documentation roles, including 7 years at Google.

Here are (more)

The most common programming languages tech writers (in my survey) know

18 hours 9 min ago
I recently surveyed technical writers to ask a variety of questions about API documentation. Rather than present a summary of the survey all at once, I am presenting the results of each question on a post-by-post basis, so that I can properly analyze and interpret the results of each question. So far about 38 people Continue Reading » (more)

Getting a job in API documentation: Podcast with Andrew Davis

Thu, 12/18/2014 - 01:58
Getting a job in API documentation can be tricky. What programming skills do you need to know? How in-depth does your technical knowledge need to be? What kind of authoring tools and methods are relevant for jobs in API documentation? In this podcast, I talk with Andrew Davis, a former technical writer who turned to Continue Reading » (more)

The most popular type of APIs that technical writers document

Wed, 12/17/2014 - 11:54
I recently surveyed technical writers to ask a variety of questions about API documentation. Rather than present a summary of the survey all at once, I am presenting the results of each question on a post-by-post basis, so that I can properly analyze and interpret the results of each question. Overall about 32 people participated Continue Reading » (more)

I need your responses to my API Documentation Survey

Fri, 12/12/2014 - 10:16

I’m trying to gather more information about common practices with API documentation. I created an informal, open survey about API Doc here.

It’s an openly editable Google Doc with about 10 questions. You can see others’ responses as you enter your own.

If you do any kind of API documentation, I need your participation in the survey. This will allow me to better generalize common practices with API documentation in preparation for some upcoming presentations and blo (more)

I need your responses to my API Documentation Survey

Fri, 12/12/2014 - 10:16

I’m trying to gather more information about common practices with API documentation. I created an informal, open survey about API Doc here.

It’s an openly editable Google Doc with about 10 questions. You can see others’ responses as you enter your own.

If you do any kind of API documentation, I need your participation in the survey. This will allow me to better generalize common practices with API documentation in preparation for some upcoming presentations and blo (more)

Authoring tools for startups — Guest post by Vinish Garg

Thu, 12/11/2014 - 11:32

The following is a guest post by Vinish Garg, an information architect with a background in technical writing who frequently works with startups. 

Vinish Garg shares his thoughts on authoring tools for startups

A discussion on authoring tools invariably leaves the participants with at least one common opinion–they want to see something better in whatever tool they are using. I recall a Wishlist post that Tom wrote a few yea (more)

Authoring tools for startups — Guest post by Vinish Garg

Thu, 12/11/2014 - 11:32

The following is a guest post by Vinish Garg, an information architect with a background in technical writing who frequently works with startups. 

Vinish Garg shares his thoughts on authoring tools for startups

A discussion on authoring tools invariably leaves the participants with at least one common opinion–they want to see something better in whatever tool they are using. I recall a Wishlist post that Tom wrote a few (more)

Podcast download stats kind of mind-blowing

Tue, 12/09/2014 - 16:00

I measure download links for podcasts through Podtrac. I haven’t been doing as many podcasts as I used to do. But I checked my podcast stats the other day and was kind of shocked.

Typical download stats for podcasts in the past averaged about 700 downloads per episode. For example, take a look at this podcast report and you’ll see that in 2011, when podcasting was supposedly popular, average downloads were about 600-700 per epi (more)

Podcast download stats kind of mind-blowing

Tue, 12/09/2014 - 16:00

I measure download links for podcasts through Podtrac. I haven’t been doing as many podcasts as I used to do. But I checked my podcast stats the other day and was kind of shocked.

Typical download stats for podcasts in the past averaged about 700 downloads per episode. For example, take a look at this podcast report and you’ll see that in 2011, when podcasting was supposedly popular, average downloads were about (more)

DITA: Glossary terms and acronyms

Fri, 12/05/2014 - 02:21

One of my colleagues was asking about best practices with glossary terms and acronyms in DITA today, and I realized that this is a pretty confusing aspect of DITA. I spent a good chunk of time trying to sort it out and outline best practices. I added a topic to my DITA QRG called Acronyms and glossary terms.

Overall, I think glossaries are underused in help material. We become numb to our own jargon, which makes help material m (more)

DITA: Glossary terms and acronyms

Fri, 12/05/2014 - 02:21

One of my colleagues was asking about best practices with glossary terms and acronyms in DITA today, and I realized that this is a pretty confusing aspect of DITA. I spent a good chunk of time trying to sort it out and outline best practices. I added a topic to my DITA QRG called Acronyms and glossary terms.

Overall, I think glossaries are underused in help material. We become numb to our own jargon, which makes help material m (more)

Convert Markdown Content to DITA in 20 seconds

Wed, 12/03/2014 - 16:44

A while ago I posted some thoughts on converting Markdown to DITA. I refined this conversion process using the Multimarkdown script and OxygenXML. Here’s a demo:

(There’s no audio to this 20 second video — it just loops over and over.)

I added more details on how to configure this in my DITA QRG: Author in Markdown, Publish with DITA.

Why would you (more)

Convert Markdown Content to DITA in 20 seconds

Wed, 12/03/2014 - 16:44

A while ago I posted some thoughts on converting Markdown to DITA. I refined this conversion process using the Multimarkdown script and OxygenXML. Here’s a demo:

(There’s no audio to this 20 second video — it just loops over and over.)

I added more details on how to configure this in my DITA QRG: Author in Markdown, Publish with DITA.

Why would you (more)

The Upcoming TC Camp Unconference and my morning API workshop

Fri, 11/28/2014 - 12:01

On Saturday, January 24, 2015, there will be a TC Camp unconference held at Mission College in Santa Clara, California. The unconference is a one-day event that draws about 150–200 technical writers in the area to participate in an informal, attendee-led day of events.

During the morning of the unconference, there are several workshops available (for a small fee). This year Marta Rauch will teach a workshop on mobile, Maxw (more)

The Upcoming TC Camp Unconference and my morning API workshop

Fri, 11/28/2014 - 12:01

On Saturday, January 24, 2015, there will be a TC Camp unconference held at Mission College in Santa Clara, California. The unconference is a one-day event that draws about 150–200 technical writers in the area to participate in an informal, attendee-led day of events.

During the morning of the unconference, there are several workshops available (for a small fee). This year Marta Rauch will teach a workshop on mobile, Maxw (more)

Upcoming API Workshop with Sarah Maddox

Fri, 11/28/2014 - 11:35

Sarah Maddox will be teaching a full-day technical writing API workshop at the Google campus in Mountain View, California, on January 23, 2015. You can read all the details here.

This workshop is free and includes a catered lunch. It will be held on Friday, January 23, from 9am to 4pm. There is no cost to the workshop, but there is a capacity limit of 110 people for the room. If you want to attend, sign up now so you have a spot.

If you change yo (more)

Upcoming API Workshop with Sarah Maddox

Fri, 11/28/2014 - 11:35

Sarah Maddox will be teaching a full-day technical writing API workshop at the Google campus in Mountain View, California, on January 23, 2015. You can read all the details here.

This workshop is free and includes a catered lunch. It will be held on Friday, January 23, from 9am to 4pm. There is no cost to the workshop, but there is a capacity limit of 110 people for the room. If you want to attend, sign up now so you have a spot.

If you change yo (more)

Tech comm on a map: See all the tech comm groups, meetups, conferences, events, and consultants on a Google map

Tue, 11/25/2014 - 15:28

Sarah Maddox recently recently launched a project called Tech Comm on a Map. It lists all the tech comm groups, meetups, conferences, events, and consultants on a Google map. You can filter by the type of content you want to see. Check it out here:

What’s nifty about this map is how you feed data into it. There’s a Google spreadsheet that has certain data columns, including longitude and latitude. The map automatically pulls in data from the spreadsheet and pl (more)

Tech comm on a map: See all the tech comm groups, meetups, conferences, events, and consultants on a Google map

Tue, 11/25/2014 - 15:28

Sarah Maddox recently recently launched a project called Tech Comm on a Map. It lists all the tech comm groups, meetups, conferences, events, and consultants on a Google map. You can filter by the type of content you want to see. Check it out here:

What’s nifty about this map is how you feed data into it. There’s a Google spreadsheet that has certain data columns, including longitude and latitude. The map automatically pulls in data from the spreadsheet and pl (more)