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: 2 hours 42 min ago

My pros and cons of using Jekyll for documentation

Tue, 11/17/2015 - 03:00

We had a lively turnout at the last STC meeting. By lively, I think we had about 30+ people in attendance, and good all-around discussion.

I had the chance to meet several new people, and one person mentioned that he reads my blog; as a bonus, he had positive things to say. We got to talking, and the conversation turned to DITA (in part because of Sarah OKeefe's recent post about the controversy in (more)


Mon, 11/09/2015 - 03:00

Can you replace a CCMS with version control such as Git or Mercurial?

Fri, 11/06/2015 - 03:00

For most of my technical writing career, although I've often worked with other technical writers, the projects have usually been independent of each other. The other technical writers worked near me but on other projects. We coordinated with styles and tools, but we didn't have to push topics from one project into another.

Now, however, I'm documenting a product whose primary purpose is to be a component integrated into other products at the same company. As a result, a lot of my documentation needs to be integrated into the documentation of other products.

Previ (more)

Tell me about your career as a technical writer...

Wed, 11/04/2015 - 03:00

A reader asks a few questions:

Can you describe a day in the life of a Technical Writer?

Sure, here is my typical day:

  • Take kids to school, then ride bike to work (just 3 miles from home, hooray!).
  • Check latest activity on JIRA, Confluence, email (a remote team in Sri Lanka works in an opposite time zone, so there's sometimes lots of activity during the night).
  • Load up several items of work. I'm trying out a technique called "kanban." You limit the number of work items on your plate to a set number of cards, which I have disp (more)

Why incremental regeneration in Jekyll 3.0 is such a big deal

Wed, 11/04/2015 - 03:00

Last week at the Static Web Tech Meetup in San Francisco, Parker Moore (the primary maintainer of the Jekyll project) announced the release of Jekyll 3.0. In the meetup presentation, Parker covers the main features in the Jekyll 3.0 release.

You can also read the brief Jekyll 3.0 release notes.

I've been playing around with some of these new features. Incremental regeneration is probably the biggest feature in 3.0 for me (more)

Increase efficiency 24 times faster when fixing errors — implications for technical writers on agile teams

Tue, 10/27/2015 - 03:00

Scrum: The Art of Doing Twice the Work in Half the Time is one of the best books I've listened to in a long time. Although I've worked in agile environments for the last decade, I don't think I fully understood the way agile is supposed to work until listening to this book.

This book should be standard reading material for any technical writer, because it will orient you about how to operate successfully in an agile environment (more)

Podcast: Spec-driven Development of REST APIs, with a focus on RAML — interview with Michael Stowe

Mon, 10/12/2015 - 03:00
b {font-size:115%;} Note: If you're in the Bay area, come listen to Michael Stowe speak tonight (Monday, Oct 12) at the STC Silicon Valley chapter in Santa Clara. See the meeting details here.

In this episode, I interview Michael Stowe, author of (more)

Udemy podcast (with me) and infographic on technical writing

Tue, 10/06/2015 - 03:00

Recently Alex Bankoff from Udemy interviewed me for a podcast on technical writing. He and his team also created an infographic based on the podcast as well. You can check out both the podcast and infographic here:

The infographic adds both visual appeal and provides a nice summary for the podcast.

The main purpose of the podcast/infographic is to help promote the technical writing courses available on Udemy, which (more)

5 REST API resources to add to your reading list

Sat, 10/03/2015 - 03:00

Here are a few good REST API resources to add to your reading list:

  • An API a Day. This is a Tumblr blog by Lois Patterson. She's provides brief updates on different API resources she finds.
  • Undisturbed REST: A Guide to Designing the Perfect API. This is a free book (written by Michael Stowe) that you can download in PDF format. It covers how to design a REST API, with an emphasis on using the RAML spec. Reading this book has helped me understand the philosophy (more)

Tutorial for creating interactive consoles with RAML

Sat, 10/03/2015 - 03:00

Following on the Swagger tutorial I posted about the other week, this week I'd like to point you to my RAML tutorial.

This is part of my larger API doc course, so in this tutorial I'm taking a simple Weather API from Mashape and putting the API's endpoints, parameters, and sample responses into the RAML spec. Then I publish that API into several different RAML outputs using API Console, Mulesoft's Anypoint Platform, and RAML2HTML.


Question: If you weren't a technical writer, what would you be?

Fri, 10/02/2015 - 03:00

A reader asks,

If you weren't a technical writer, what would you be? Also, is there anything you'd still like to accomplish and experience professionally?

If I weren't a technical writer, I would be a web designer. I love the web and how it has revolutionized and empowered the masses to publish content, interact with each other, find information, build networks, and cross boundaries. I worked as a WordPress consultant on the side of my regular work for about 5 years, before becoming too busy for it. Lately I've put WordPress on the backburner while I focus (more)

Why so little focus on API doc at tech comm conferences?

Wed, 09/30/2015 - 03:00

Either I'm becoming more distanced from mainstream tech comm topics, or else tech comm conferences are veering away from trending topics. I can't decide who is moving off course.

I'm interested in API documentation. It seems like API documentation is one of the hottest trends in the San Francisco Bay area and other IT hubs as well.

And yet, in browsing the agenda of the current conferences this season — Lavacon, Information Development World, and Tech Comm UK — topics related to API documentation are virtually non-existent. There's maybe one wor (more)

Question: Can I earn a living blogging?

Wed, 09/30/2015 - 03:00

A reader asks,

Can I earn a living by writing a blog? How do blog writers make money? I'm an English major exploring my options.

There's almost no money in blogging. I have some ads that I got by asking companies if they wanted to be a sponsor, but ads don't create much revenue.

Blogging's real value is in establishing yourself as an expert in a field. This gives you credibility with employers and other professionals. For example, I'm teaching some API workshops that I got mainly through notoriety from my blog.

So first ask yourself wh (more)

Question: How long has your API doc course been available?

Tue, 09/29/2015 - 03:00

A reader notes:

I only just today discovered your API Doc Course. Well done! Thanks very much for this. How long has this course been available? Are you still working on the material?

I've been working on this material for the past several months. It's gone through several iterations. From presentations and short workshops on API documentation over the past year, the material has evolved and grown, and I'm trying to add more detail and polish to the content in order to convert it into an online (more)

Question: How are you publishing and delivering your docs?

Tue, 09/29/2015 - 03:00

A reader asks,

How are you publishing and delivering your documentation these days?

As far as publishing, I'm using Jekyll with this doc theme I created. (You can see the Github source here.)

To deliver the content, I have several channels. For internal audiences, I upload the HTML output onto an internal server using FTP. For external audiences, I upload the HTML output into a (more)

Question: How do I tell what platform people are using for API docs?

Mon, 09/28/2015 - 03:00

A reader asks,

How can I tell what platform people are using to publish their API docs? What are the most common tools used for building developer documentation sites?

If you look in the source code of the site, look for signs of a platform. Sometimes with web CMSs, it's obvious. If you see "wp-content," it's a WordPress site. If you find the word "drupal," it's a Drupal site.

If the site loads slowly, it might be dynamically serving content from a database, so it could be another web CMS.

Static site generators are often u (more)

Experimenting with a shorter post style

Sat, 09/26/2015 - 03:00

I'm thinking about leaning toward a shorter style for blog posts. Lately I've been focusing a lot of energy on developing an API documentation course, so although it may not appear as if I'm posting as much, I'm actually writing quite a bit here.

The difference between posts and pages on a blog is becoming less important. Posts appear in an RSS feed and are intended as diary-like entries that live on the homepage a few weeks before sliding into oblivion. In contrast, pages are intended to be more per (more)

Adding native library API section to API doc course

Sat, 09/26/2015 - 03:00

I added a section to my API documentation course on "native library APIs".

I'm never quite sure what to call these kinds of APIs, but it seems that "native libraries" is better than either platform APIs, library APIs, or class-based APIs for the following reason:

"Platform APIs" gets confused with API platforms that actually have APIs for managing your content on the platform. "Library APIs" gets confused with APIs focused literally on libraries and library sc (more)

Upcoming "Ask Me Anything" (AMA) session

Mon, 09/14/2015 - 03:00

If you've ever seen the AMA ("Ask Me Anything") posts on Reddit, they're special themes in which an interesting or famous person makes him- or herself available for questions about anything for about an hour.

Vinish Garg is following this same pattern on Content Hug, and he invited me to do an AMA session on his site. The AMA is scheduled for Thursday, September 17 at 9:00am PST for one hour.

For details, see the details on Conten (more)

Swagger tutorial for REST API documentation

Mon, 09/14/2015 - 03:00

Swagger is a REST specification that allows you to generate interactive API documentation. I created a tutorial for using Swagger in the API doc course I'm working on.

In my Swagger tutorial, I show you how to use the Swagger Petstore example as well as how to build your own Swagger output. If you go through the tutorial, let me know if you have any feedback.