API documentation survey 1.0 → I need your responses to my API Documentation Survey 1.1 API doc survey: The most popular type of APIs that technical writers document 1.2 API doc survey: The most common programming languages tech writers know ...
The following is a guest post by Vinish Garg, an information architect with a background in technical writing who frequently works with startups. Vinish Garg shares his thoughts on authoring tools for startups A discussion on authoring tools invariably leaves the participants with at least one common opinion–they want to see something better in whatever tool they are using. I recall a Wishlist post that Tom wrote a few years back; I am...
I measure download links for podcasts through Podtrac. I haven't been doing as many podcasts as I used to do. But I checked my podcast stats the other day and was kind of shocked. Typical download stats for podcasts in the past averaged about 700 downloads per episode. For example, take a look at this podcast report and you'll see that in 2011, when podcasting was supposedly popular, average downloads were about 600-700 per episode. Sinc...
One of my colleagues was asking about best practices with glossary terms and acronyms in DITA today, and I realized that this is a pretty confusing aspect of DITA. I spent a good chunk of time trying to sort it out and outline best practices. I added a topic to my DITA QRG called Acronyms and glossary terms. Overall, I think glossaries are underused in help material. We become numb to our own jargon, which makes help material much more di...
A few weeks ago I was riding out near Stevens Creek park when I came across a bicycle painted white. In front of it were two gravestones, giving memory to two cyclists who were killed by a motorist at that spot. One of the gravestones said, Rethink what is possible. The other gravestone said: Free from limitations and imaginary lines. As I rode away, I thought about the second gravestone. I wondered if it was original and later...
A while ago I posted some thoughts on converting Markdown to DITA. I refined this conversion process using the Multimarkdown script and OxygenXML. Here's a demo: (There's no audio to this 20 second video -- it just loops over and over.) I added more details on how to configure this in my DITA QRG: Author in Markdown, Publish with DITA. Why would you want to convert from Markdown to DITA? Mainly, you would use...
On Saturday, January 24, 2015, there will be a TC Camp unconference held at Mission College in Santa Clara, California. The unconference is a one-day event that draws about 150–200 technical writers in the area to participate in an informal, attendee-led day of events. During the morning of the unconference, there are several workshops available (for a small fee). This year Marta Rauch will teach a workshop on mobile, Maxwell Hoffman will...
Sarah Maddox will be teaching a full-day technical writing API workshop at the Google campus in Mountain View, California, on January 23, 2015. You can read all the details here. This workshop is free and includes a catered lunch. It will be held on Friday, January 23, from 9am to 4pm. There is no cost to the workshop, but there is a capacity limit of 110 people for the room. If you want to attend, sign up now so you have a spot. If you ...
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...
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 topic in my DITA QRG that contains a link to a demo of the content filter. When you select an option in the upper-right...
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 used a jQuery plugi...
I'm starting to lump together weekly posts into a theme but also include some other details. This isn't necessarily a bike journal (given the post title, you might think that), but the rides are sometimes more fun to document. Callie is learning to play the violin. She is still in the plucking stage, so she hasn't been taught the bow yet. She wanted to give up last week because she couldn't get the finger crawl method down with a pencil (it'...
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 them work for small companies or startups, and they may be the only writer or play a hybrid rol...
This post is brought to you by 34SP.com, a website hosting company made up from skilled hosting professionals who offer exceptional customer service and technical support. Note: I don't often publish guest posts from sponsors, but I think this 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 techni...
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 de...
