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...
Listen here: In this podcast, I talk with Mark Baker from Every Page Is Page One about unifying the API doc publishing toolchain. Here are some questions I ask Mark during the podcast: What kinds of API docs pose challenges with the tool chain? Do API reference docs need to be separate from other docs? How do you integrate API reference with non-API reference info? How do you extract source code comments from Java or C+...
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 ...
