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.
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)
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.
A reader asks a few questions:
Can you describe a day in the life of a Technical Writer?
Sure, here is my typical day:
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)
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)
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)
Here are a few good REST API resources to add to your reading list:
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.
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)
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)
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)
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)
A reader asks,
How are you publishing and delivering your documentation these days?
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)
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)
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)
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)
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.
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.(more)