New series: User-centered documentation

I’m starting a new series on my blog about user-centered documentation. If you’re new to my blog, a series is a collection of posts (usually about 10) focused on the same topic. The series format gives me a chance to explore a topic in depth without publishing a monolithic post all at once. Origins of Continue Reading »

Final analysis between DITA and Jekyll

As the ninth post in this series, I think I’m wrapping it up. This post will contain my final analysis comparing Jekyll with DITA. During this series, I had the misfortune of cutting a tendon in my thumb with a box cutter knife, and so typing has been difficult. I’ve had to wear a cast Continue Reading »

Producing PDFs in DITA versus Jekyll

In this near final post in my series comparing DITA with Jekyll, I want to explore contrasting ways to produce PDFs. I have other blog posts where I have stated how much I dislike PDFs with technical documentation. The main problem is that even though PDFs go out of date quickly, users hang onto them Continue Reading »

Reviewing content in DITA versus Jekyll

This is another post in my series comparing DITA against Jekyll. In this post, I want to compare reviewing methods for the two systems. Theoretically, you could review content from both systems in the same way. But you could also take very different approaches to reviewing content as well. How to review content in Jekyll Continue Reading »

Creating links in DITA versus Jekyll

In this ongoing series, I’m comparing tech comm techniques with DITA versus Jekyll, a popular static site generator. How you create links is more than a simple technical detail. Linking is one of the main strategies for connecting and interrelating information. How to create links in DITA In DITA, you have several choices for making Continue Reading »

Newbie to Technical Writer in 4 Easy Steps


The following is a guest post from Kaylin Tristano, a new technical writer in the medical software industry. In this post, she shares her tips for transitioning into the field of technical writing. I landed my first technical writing job about four months ago. I’d been working as a librarian and had no writing experience Continue Reading »

Building a table of contents with DITA versus Jekyll

In my ongoing series comparing Jekyll against DITA, I want to touch on how you construct a table of contents. Creating a TOC with DITA The ditamap file in DITA is arguably the most important file in a DITA project, and it has a lot of features. Basically, the ditamap defines the table of contents Continue Reading »

Creating re-usable chunks (conref) in Jekyll versus DITA

In my previous post, I explained how to do variables and conditional processing in Jekyll. One of the commenters wondered about how you create “intelligent content” with Jekyll: how does a Jekyll (or similar) approach let us create intelligent content? There was a recent conference in San Francisco focused on intelligent content, and one of Continue Reading »

Variables and conditional processing in Jekyll versus DITA

In the previous post, I compared writing in Markdown versus writing in XML. In this post in the series, I want to look at variables and conditional processing between the two platforms. Variables in Jekyll In Jekyll, you can assign a variable a specific value, like this: Now you can use {{dog_name}} in your content Continue Reading »