A long list of technical innovations semi-relevant to technical writers

Innovation in tech comm 1.0 Sustaining and disruptive innovations 1.1 → A long list of technical innovations semi-relevant to technical writers 1.2 The only significant innovation for tech comm 1.3 XML and the web: drifting farther apar...

Sustaining and disruptive innovations

Innovation in tech comm 1.0 → Sustaining and disruptive innovations 1.1 A long list of technical innovations semi-relevant to technical writers 1.2 The only significant innovation for tech comm 1.3 XML and the web: drifting farther apar...

Podcast: The upcoming tcworld India conference on March 12-13, with Akash Dubey

Listen here: This weekend I talked with Akash Dubey, one of the main organizers of the tcworld India conference, about the upcoming conference in India. Although I haven't mentioned it on my blog yet, this year I'm actually attending tcworld India as an invited keynote presenter. tcworld India is a joint effort by two groups: Technical Writers of India (commonly known as TWIN) and tekom (the same group that creates the ...

Why do we need PDFs?

I've never been a fan of PDFs, but PDF output is usually a requirement someone invariably brings up for documentation. In some cases, often for unstated reasons, users will ask for a PDF, and product managers expect technical writers to deliver one. When I get these requests, I usually create a zip file of the website and send it to the user, instructing the user to click the index file to launch it. This works well for these two situatio...

Upcoming workshop: Creating Interactive Video Tutorials, with Bernard Aschwanden on Feb 21

If you're in the San Francisco Bay area and are interested in learning how to create interactive video tutorials, we have a workshop just for you. The STC Silicon Valley chapter is hosting a workshop titled Best Practices when Creating Interactive Video Tutorials. The workshop is led by Bernard Aschwanden -- a consultant at Publishing Smarter and the Vice President of the general STC. The workshop will take place on Saturday, Feb. 21, fr...

Best practices for API documentation -- podcast with Andrya Feinberg

I recently talked with Andrya Feinberg, a documentation manager and content strategist for Emotient, about best practices with API documentation. Below is a writeup Andrya has provided that summarizes some of the points she makes in the podcast. Listen here: Here is Andrya's summary of the best practices: API Documentation Best Practices, by Andrya Feinberg In the world of Technical Communication, Content Strategy, Use...

Survival strategies for API documentation -- slides and recording

I'm gave a webinar to the Southern Ontario STC on Monday, Feb 2. This post contains the slides and recording. Webinar description Survival strategies for API documentation If you're documenting an API for the first time, you may be in survival mode just trying to decipher the code, unravel developer speak, and publish a coherent set of documentation. API documentation is a new landscape for most technical writers. Traditional platform AP...

Creating context-sensitive help by converting your help into a JSON API with Jekyll

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...

Writing is like sorting laundry -- practical advice for tackling documentation projects

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 ...

10 reasons for moving away from DITA

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...

API workshop video + audio + slides + workshop files from TC Camp

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 ...

Reinventing the table of contents

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...

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

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...

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

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...

Most important factor in APIs is complete and accurate documentation

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 ...