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...
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...
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...
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, 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...
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...
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...
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 ...
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've been knee-deep in Atlassian Confluence lately, analyzing the best way to re-use content. In this post, I'll describe a fictitious scenario that resembles an advanced content re-use situation and then explore various strategies for re-use. The scenario Suppose you're creating a bicycle manual for a Trek 7.3 FX (which happens to be the exact bike I recently bought). There's a 7.1 FX and 7.2 FX model for the Trek bike, which you're also...
As I started my new job, I've been thinking about the most important technical writing principles I've learned in the past. The following are 10 principles to live by when doing technical writing. 1. Always test out the instructions yourself. Unless you can walk through the instructions and perform the tasks yourself, it will be difficult to evaluate the help material. Testing the instructions seems like a given, and with GUI documentatio...
Listen here: In this podcast, I talk with Scott Abel and Val Swisher, organizers for the Information Development World conference, about the technical writer's role in the customer experience. The customer experience is a major focus of the Information Development World conference. The Information Development World conference will be held in San Jose, California on October 22-24, 2014. Here are some of the topics we t...
Listen here: In this podcast, I talk with Scot Marvin, an API technical writer based in Oregon, about some introductory topics with API documentation. Topics covered in the podcast include the following: The prevalence of APIs 15 years ago compared to today The definition of an API What technical writers are responsible to document with APIs Where technical writers get information about the requests, parameters, and ot...
I started a new job last Monday at a company called The 41st Parameter in San Jose. I'm pretty excited about it. 41st's main product helps prevent online fraud with transactions; another product helps with identity resolution for advertising technologies. I'll be creating developer documentation for products that include C++, Java, .NET, and REST. I'll also probably be using Confluence. I'm one of 3 writers, but 2 are based on Arizona, w...
Listen here: In this podcast, I talk with Mary Linderman, a technical writer in Chicago who has been doing API documentation for the past couple of years, about her experiences in the API documentation space. Mary recently wrote an article called "Lessons learned from a novice API writer" for an upcoming issue of STC Intercom that I'm editing, and I wanted to record a podcast with her to capture some of her thoughts. In...
