Adding code comments through a sliding jQuery Sidr panel (DITA)

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

STC Intercom Issue Entirely Dedicated to API Documentation

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

Using WordPress natively for single source publishing and conditional content

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

Upcoming presentation in downtown San Francisco: Publishing strategies for API documentation

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

Challenges in using WordPress for publishing DITA content

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

Thirteen life hacks

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 with WordPress

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

Woes of conditional text and topichead elements (DITA best practices)

When authoring in DITA, there are a couple of best (or worst) practices that I wasn't aware of. The first is with conditional text; the second is with topichead elements: Cautions with conditional text Noz Urbina has written two excellent articles about the dangers of going overboard with conditional text. When Conditional Content Goes Wild: 4 Top Tips for Avoiding Pain – Part 1 When Conditional Content Goes Wild – Part 2: Securing Supp...

Benefits of tool diversity, part II

In my previous post, Is tool fragmentation a good thing?, I lamented the trend toward tool fragmentation in the tech comm community, noting several disadvantages that fragmentation brings: fragmentation of community and knowledge sharing increased overhead of learning new tools frustration with HR departments who expect strong knowledge of their chosen tool (among hundreds) I explored the appeal in having a standard method for tech com...

Is tool fragmentation in tech comm a good thing?

One of the attendees from Alan Houser's recent presentation at InfodevDEC meetup in Virginia the other night noted the following: #techcomm trends/hypes, from @arh: There's no one technology that a majority of people are using. @infodevdc — John Collins (@jrc_collins) August 4, 2014 Juxtapose this tweet about Alan's presentation with the recent WritersUA Tools Survey from Joe Welinske, which pretty much reflects the same trend...

Reviewing draft DITA content with subject matter experts: 6 essential points

Lately I have been exploring different ways to let subject matter experts review DITA content. In a previous post, I explored using easyDITA to facilitate the review. In this post, I'll explore OxygenXML's Webhelp with Feedback output for conducting the reviews. What makes for a good review process? By far the best review method I've ever used was at Badgeville with Google Docs. Because all employees used Google Docs for their business su...

My DITA quick reference guide (QRG)

My DITA quick reference guide, or DITA QRG, is available on my menu bar and here: https://idratherbewriting.com/ditaqrg/. This DITA QRG consists of my own notes for working with DITA. My DITA quick reference guide Why create this quick reference guide? There's a lot to know about DITA. If you look at the DITA 1.2 spec there are many, many elements -- it can be overwhelming when trying to start out. Additionally, I think DITA could benef...

Book Review: The Goldfinch, by Donna Tartt

I don't often review fiction on this site because I made a decision long ago to brand this site as being specifically about tech comm. But a couple of recent posts by my blogging friends (Neil Kaplan and Sarah Maddox) remind me that it's good to show more than one side of a person. I wouldn't want you to think that my sole interest and passion in life is technical writing. I have a lot of other interests and thoughts. I would hope that re...

Writing documentation in an interactive world: Some thoughts on using easyDITA and OxygenXML

Since moving to DITA, I've tried to settle on best practices and determine the authoring method that works best for me. I started out using OxygenXML, which is one of the most popular DITA editors. I like OxygenXML because it's easy to work with the code. OxygenXML knows when to show you a list of all possible elements or values you can insert in your topic at any time. For example, if you type , the editor prompts you with values you can...

The part of the brain you should listen to when writing

In This is your brain on writing, Carl Zimmer writes: A novelist scrawling away in a notebook in seclusion may not seem to have much in common with an NBA player doing a reverse layup on a basketball court before a screaming crowd. But if you could peer inside their heads, you might see some striking similarities in how their brains were churning. The article caught my attention because, actually, I love basketball. I play it a couple of ...