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