12/2/15 update: For more technical details on how to convert Markdown to HTML to DITA, see Convert Markdown to DITA in 20 seconds. 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 dre...
Lucy had an assignment to choose 7 pictures that demonstrate the timeline of her life. Although we didn't scour all every digital folder of pictures, here are 7 fun pictures of Lucy.
This morning Shannon and I left early (about 8am) for a ride up the San Francisco Bay Trail. We were planning to ride all the way into the city (i.e., San Francisco), but we got turned around a few times on the Bay trail, and it so happens that much of the Bay trail is gravel, so you can't go that fast on it. A couple of weeks ago I ordered a comprehensive map of the Bay trail, thinking it would be a perfect riding route. I didn't realize th...
I had the opportunity to attend Ed Marshall's API and SDK workshop at Information Development World. These are my notes. APIs versus SDKs SDKs are a set of tools that developers can use to make it easier to work with an API. Ed said that at one company, the SDK was a GUI tool of some kind that made it easier to interact with the company's API. (When I worked at Badgeville, our JavaScript SDK made it easy to work with the REST API through ...
Voiceover techniques 1.1 Finding a Conversational Voice in Video Tutorials 1.2 The Problem with Speaking Conversationally in Video Tutorials 1.3 Finding an acoustic environment (Voiceover) 1.4 Sounding natural (Voi...
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...
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 y...
Shannon and I rode an 18 mile loop across San Francisco (following the Wiggle route), through the Golden Gate park, around the coast to the Golden Gate Bridge, across the Bridge up to Sausalito, onto the Sausalito Ferry back to the Ferry Building at San Francisco. The ride is 18 miles long, not counting the distance the ferry covers. Here are some photos from the trip: (There are also a few photos in this album from the day before at the N...
We spent the weekend at Yosemite, camping two nights at "Housekeeping camp." Here are some pictures from the trip: I decided to start a log of what worked well and what didn't for each trip. From Lucy's point of view What worked well Playing in the lake -- wading in river, catching crawdads, climbing on the rocks under the bridge Sleeping in the beds in the housekeeping structures Seeing fat squirrels Riding bikes on the trails What could ...
Yesterday I presented "Publishing strategies for API documentation" to the San Francisco STC chapter. Here are my slides and recording. Listen here: Publishing strategies for API documentation from Tom Johnson PowerPoint in other format: pptx | zip Also, I know I posted it earlier, but here's the description of my presentation. Publishing strategies for API documentation Most of the common tools for publishing help ...
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: Created a way to include the TOC navigation from the XHTML import automatically. Changed the installation method so th...
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...
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</uicont...
Last week we went to Natural Bridges. Here are some photos: This is one of my favorite beaches for several reasons. There's a large area with tide pools that is simply fun to explore. Usually there are sea anemones all over here, but not today. Even so, it's a lot of fun to look in the tide pools while the ocean is crashing on the shore to your side. Callie wanted to explore a remote pond, and I reluctantly followed. To our amazement, we ...
It's been way too long since I've updated this blog. I am trying to get back into the habit. I'm not sure where to start, so I decided to just upload some pictures and add some captions. We ride to school pretty regularly, so this is what it looks like at about 7:45am. Avery likes to ride alone, though, and when I said, Okay, let's roll on out, she sighed and waited for us to leave before rolling out herself. Lucy earned a PAW award at schoo...
