I've written a lot about documenting APIs, but what if your documentation itself could function as an API? By this I mean, what if you could give developers an endpoint through which they could retrieve different parts of your documentation? This setup would work well for context-sensitive help within an application. I stumbled across a cool Jekyll plugin called Jekyll Pages API that actually allows you to do this. The plugin creates a JS...
A reader recently asked, This is sort of a beginner question, although I am not technically a beginner. I've been helping to maintain a medium sized doc set for a suite of products at a large company for over ten years. I've never written a significant document from scratch in my 10+ years as a technical writer -- I've written new topics, documented new features, and written more release notes than I can count. Now my manager expects me ...
My DITA journey 1.0 My DITA journey begins 1.1 DITA: Folder hierarchy, conref, mapref, and more 1.2 DITA: Why DITA, metadata, working in code and author views, and relationship tables 1.3 DITA hierarchical links, r...
I recently gave an API workshop at the TC Camp Unconference last weekend in Santa Clara, California. This post includes a video recording of my presentation, along with slides, audio, and workshop files. I actually prepared four separate slide decks for the workshop, but only used 2 and a half of them. I don't know why I prepared so much. In the back of my mind, I was thinking that I could just use all of this material for a udemy course ...
I've been exploring different ways to create a table of contents (TOC). Traditionally, user guides have a long TOC in the left column of each page. This works all right when you have about 50 pages, but when you scale up the doc set to 500 pages, the TOC becomes a bulky, unusable mess. For an example of the mess I'm talking about, see this TOC in Salesforce's documentation. An all-encompassing TOC model like this essentially repeats the i...
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 the active heading in your mini-table of contents. What is ScrollSpy To better understand ScrollSpy, go t...
The following is a recording of a presentation about passive versus reactive documentation by Greg Koberger, developer and designer for ReadMe.com, 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 the Docs meetup group in San Francisco.) Listen here: You can view the sl...
API documentation survey 1.0 I need your responses to my API Documentation Survey 1.1 API doc survey: The most popular type of APIs that technical writers document 1.2 API doc survey: The most common programming languages tech writers know ...
API documentation survey 1.0 I need your responses to my API Documentation Survey 1.1 API doc survey: The most popular type of APIs that technical writers document 1.2 API doc survey: The most common programming languages tech writers know ...
API documentation survey 1.0 I need your responses to my API Documentation Survey 1.1 API doc survey: The most popular type of APIs that technical writers document 1.2 API doc survey: The most common programming languages tech writers know ...
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 Aeris Weather example Flickr example If you feel like walking through them, trying them out, and giving me feedback, that would be helpful. I chose 3...
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 backed by databases were all the rage. WordPress, Joomla, Drupal, Alfresco, Blogger, Typepad we...
API documentation survey 1.0 I need your responses to my API Documentation Survey 1.1 API doc survey: The most popular type of APIs that technical writers document 1.2 API doc survey: The most common programming languages tech writers know ...
If you're in the San Francisco Bay area (near Santa Clara), come join us Monday, January 12 at around 7pm for a presentation by Greg Koberger on passive versus reactive documentation, plus a demo of readme.com docs, which is a new cloud platform for REST API documentation that is extremely well-designed. I saw Greg present at a Write the Docs meeting a few months ago and was impressed. He said he is designer who is obsessed about technica...
Someone recently asked me: I am using DITA with structured Frame and Tech Comm Suite. Do you know the best output to use so the docs can be displayed in Confluence? The SMEs want to proofread in Confluence and use it for a knowledge base. Ideally, I'd like to output from DITA or Robohelp and then just upload to Confluence. Great question! Mixing DITA and Confluence is a major challenge. I noted in my API doc survey that about a third of p...
