Post a note under our blog aggregation requests if you want your blog added to our aggregator. Please provide the RSS feed URL and the title of your blog.
Sarah Maddox recently recently launched a project called Tech Comm on a Map. It lists all the tech comm groups, meetups, conferences, events, and consultants on a Google map. You can filter by the type of content you want to see. Check it out here:
What’s nifty about this map is how you feed data into it. There’s a Google spreadsheet that has certain data columns, including longitude and latitude. The map automatically pulls in data from the spreadsheet and pl (more)
One of the little tricks I’ve implemented with OxygenXML is dynamic content filtering. Our product supports four different programming languages – Java, PHP, C++, and .NET. Rather than producing 4 separate outputs, I produce just one output and provide a content selector option in the header.
Here’s a demo in my DITA QRG site.
When you select an option in the upper-right corner, the content dyna (more)
This is a sponsored post by Nicole Smith on the history of technical writing. I don’t often publish sponsored posts, but I think Nicole’s essay provides a brief yet informative history of the tech comm profession that is worth reading.The Internet has revolutionised communication completely, but this is especially apparent in technical writing. How often have you wanted to learn how to do something and gone to eHow or Wikipedia to learn about a skill or process? Helpful and informative written work has been around almost as long as writ (more)
A while ago, I posted a tip on adding collapsible sections to the OxygenXML webhelp output. Collapsible sections have their place, but more commonly now, users seem to prefer long pages that they can scroll. For this behavior, it’s better to add a mini-TOC near the beginning of the page that lists the sections on that page. As an example, look at pretty much any page on Wikipedia.
Here’s what my mini-TOC looks like:
I attended my first Write the Docs meetup last Thursday night in downtown San Francisco. It’s interesting to compare Write the Docs with the STC. (I was downtown at an STC SF meeting just the previous month, if you recall from an earlier post.)
What are my impressions? In general, the Write the Docs crowd is younger and more tech savvy. Many of the (more)
In Goodbye WordPress: 2014 Will Be the Year of the Flat-File CMS, Jeremiah Shoaf argues for the upcoming dominance of flat-file systems over database-driven sites such as WordPress.
I found the post extremely interesting because I’ve been moving back and forth between flat-file systems and database systems with my DITA publishing strategies. There are compelling arguments for each side.
On one hand, databases provide more capability to delivery dynamic content to d (more)
Length: 26 min.
Download MP3 (right-click and select Save As)
While I was at Information Development World, I had a conversation with Rick Yagodich about his new book, Author Experience. This is one of the first books in The Content Strategy series of books. During our conversation, Rick and I talked about the following topics:
The other day I started to organize my notes on Java, and knowing that I eventually plan to publish these notes, I wondered what format I should write the content in. My first thought was, hey, I wrote my DITA QRG in DITA, so why not store my Java notes in DITA as well?
And then I had this nasty feeling of dread where something in my chest cringes and shrivels. If I was going to be drafting this content, the last thing I wanted to worry about was XML markup tags and structural complexity.
Were I to draft the content in DITA, I (more)
Today at Information Development World I presented “Perfecting the audio narration in instructional video.” Here are my slides and recording.
PowerPoint in other format: (more)
I’m giving a presentation this week at Information Development World on voiceover with video tutorials. My presentation is Thursday at 2pm. Here’s the description:Perfecting the Audio Narration with Instructional Videos
No matter what tool you use to create video tutorials, getting the voice right — sounding professional, clear, and friendly — is an art. You have to know to interact with your microphone, how to read your script sounding natural and at ease (often while driving the mouse), how to post-process your (more)
The following is an interview with Jim Turcotte, a senior vice president for CA Technologies and business unit executive for the Information Services team. Jim recently posted several articles on LinkedIn Pulse about something he calls DocOps, so I asked him some follow-up questions.
Can you explain DocOps in more detail?
First, let me start by explaining the application economy. Customers today decide whether or not to do business with you based on your software. Your new façade is now your mobile application and online presence. A (more)
I’ve been working on some updates to the WordPress DITA Import tool. This tool allows you to import the DITA XHTML output into WordPress. For the full instructions, see this page on my demo site: Import DITA’s XHTML Output into WordPress.
I’ve mentioned this tool before on my blog, but I’ve made some updates to the tool:
If you hang out in tech comm circles, attend STC meetings and technical writing conferences, and interact on tech writer blogs and forums, you might think the general tool options for professional technical writing goes something like this: You can use a help authoring tool, such as Madcap Flare, Framemaker, or Author-it. You can also structure your content in DITA, using an editor such as OxygenXML. If you’re a big corporation, you maybe publish your content on a CMS of some kind, like SDL or Ixiasoft. If you’re in a highly collaborative environment, you might use a wiki such as Conflu (more)
Ever wonder why developers resist DITA so much? Take a look at this comparison. Here are two ways to describe a simple task of printing a page.DITA syntax <task id="task_mhs_zjk_pp"> <title>Printing a page</title> <taskbody> <steps> <stepsection>To print a page:</stepsection> <step> <cmd>Go to <menucascade> <uicontrol>File</uicontrol><uicontrol>Print</uicontrol> </menucascade></cmd> </step> <step> <cmd>Click th (more)
The other day I tweeted about a brief frustration with Confluence:
I don’t mean to be critical, but I really hate using Confluence for doc. Am so happy to be migrating Confluence content to DITA. #techcomm
— Tom Johnson (@tomjohnson) September 22, 2014
And a couple of people asked me for a post with more detail.
Last week I showed how to integrate a sliding side panel into OxygenXML’s webhelp output. In this post, I show you how to integrate collapsible show/hide sections. As before, I’m using DITA as the structured content, which adds another element of complexity to the setup.Demo
For a demo of the show/hide functionality, see Show/Hide Demo.
If you write developer documentation, you know that developers prefer code samples to narrative instruction. The beauty of code samples is that they provide context at a glance. You can see where variables should be declared, functions called, objects initialized, and so forth — all by just looking at the code. Trying to describe the same content narratively just doesn’t connect with users.
The problem is, you can only pepper the code with brief 1-2 line comments as instruction to users. These short signposts might be fine for advanced users, but for those times when you need mor (more)
The September issue of the STC Intercom is entirely dedicated to API documentation. I had the opportunity to act as guest editor for this issue. As guest editor, I helped select the topics, find the writers, and did some editing on the articles. I also wrote a foreword to the articles. It was a pretty cool experience altogether.