Implementing ScrollSpy with Jekyll to auto-build a table of contents

scrollspythumb

I mentioned in a post last week that I’m experimenting with a Jekyll prototype for technical documentation. I stumbled upon one of the coolest and most interesting topics a few days ago while integrating “ScrollSpy” on Jekyll. ScrollSpy is a dynamic feature that “spys” on the headings as you scroll past them and dynamically highlights Continue Reading »

Moving from passive to reactive documentation — recording of presentation by Greg Koberger, ReadMe.io founder

Greg Koberger

The following is a recording of a presentation about passive versus reactive documentation by Greg Koberger, developer and designer for ReadMe.io, a slick new REST API documentation tool. Greg gave this presentation at the STC Silicon Valley chapter meeting on January 12, 2015 in Santa Clara, California. (He gave a similar presentation to a Write Continue Reading »

Most important factor in APIs is complete and accurate documentation

completedocthumb

A 2013 survey by Programmable Web that included about 250 respondents found that complete and accurate documentation was the most important factor in an API: This is certainly an encouraging finding for technical writers, and suggests that more attention and focus should be given to documentation. I think I’m going to print this picture out Continue Reading »

Several REST API tutorials using the EventBrite, Klout, and Flickr APIs

gallery

In preparation for my upcoming API workshop at TC Camp, I created several REST API tutorials. These tutorials walk through the process of calling and endpoint and displaying parts of the response on a web page. Here are the tutorials: EventBrite example Klout score example Klout influenceez example Flickr example If you feel like walking Continue Reading »

Experimenting with Jekyll for tech comm

jekyllthumb

Today I had the opportunity to explore Jekyll a bit more. Jekyll is a static site generator that helps you build websites quickly. The sites can be blog sites or regular sites (or documentation sites). However they’re used, there’s definitely a trend toward static site generators over database-driven sites. Seven years ago, online CMS platforms Continue Reading »

API doc survey: Most challenging aspect of API documentation

mostdifficult

In my API documentation survey, one of the questions I asked was the following: What aspect of API doc do you find most challenging (e.g., understanding code)? This turned out to be a great question. Because the responses were open-ended, I didn’t force respondents to select from a pre-existing list. Instead, they could write whatever they Continue Reading »