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...
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. @tomjohnson Please blog it. I'd really like some detail on this. I'm becoming disillusioned with Confluence. — Berger (@Bergero...
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. In this demo, the content shown in the first collapsed section is actually transcluded from another p...
Developing User Assistance for Mobile Apps, 2nd Edition, by Joe WelinskeJoe Welinske just published his second edition of Developing Mobile User Assistance. Although it's the second edition, 300 of the 400 pages are new, making it mostly a new book. If you're doing anything related to mobile, this is a must-read book. It will get you going the right way. I had the opportunity to write a foreword to the book (which you can see here as w...
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 wit...
The September issue of the STC Intercom is entirely dedicated to API documentation (if you don't have access to STC, go to this alternative). 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. This issue of the STC Intercom is entirely dedicated...
Author in DITA, publish in WordPress 1.0 Import DITA Webhelp Output into WordPress 1.1 Author in DITA, publish with WordPress 1.2 Challenges in using WordPress for publishing DITA content 1.3 → Using WordPress natively for sing...
10/15/2014 update: For the slides and recording, see this post. I'm giving the following presentation to the San Francisco STC Chapter on October 15: Publishing strategies for API documentation Most of the common tools for publishing help material fall short when it comes to API documentation. Much API documentation (such as for Java, C++, or .NET APIs) is generated from comments in the source code. Their outputs don't usually integrate...
Author in DITA, publish in WordPress 1.0 Import DITA Webhelp Output into WordPress 1.1 Author in DITA, publish with WordPress 1.2 → Challenges in using WordPress for publishing DITA content 1.3 Using WordPress natively for single source...
The other day I ran across a post detailing 46 brilliant life hacks. Since then I've been mulling over a few of my own life hacks and wanted to share them here. The following are a few tips that have worked for me. They are totally random, covering "life" in general, but I'll share them here in case someone finds them beneficial. (Sorry that I'm too lazy to be more unique with my images. Most of these images are from Flickr.) 1. To avoid...
Author in DITA, publish in WordPress 1.0 Import DITA Webhelp Output into WordPress 1.1 → Author in DITA, publish with WordPress 1.2 Challenges in using WordPress for publishing DITA content 1.3 Using WordPress natively for single source...
