Posted in Uncategorized

Confessions of a Failed Technical Communicator

Really, Father, my only sins are beer, donuts, beer, donuts, not knowing DITA, beer, donuts…

“Bless me, Father, for I have sinned! I am a failure in technical communications.”

OK, perhaps in many eyes, I haven’t been a failure in technical communications. It will be five years this spring since I graduated with my Masters degree in Professional and Technical Communication from NJIT. In many ways, that feels like it was just yesterday, and I’m still a “new graduate”. But with the change this year in my STC Membership that’s moved from “Student” to “New Professional” to “Classic”, I supposed I’m not anymore.

While graduate school gave me a good foundation to move forward, I learned very quickly that I needed to continue to educate myself. As I attended conferences and presentations, and paid attention to discussions in social media, I found out that graduate school lessons barely cut the surface. I’ve tried my best to continue my studies by attending as many webinars, conferences, and presentations that I can. I even took another university graduate certificate course on digital marketing, hoping to get some insight that might help me going forward.

However, in the end, I failed to do one thing that might actually boost what I’m doing as a fledgling content strategist, and thus, my confession: I needed to learn DITA.

For those of you who don’t know what DITA is, it’s the acronym for Darwin Information Typing Architecture, and it’s a commonly used method for creating structured authoring using XML coding. The idea is that documentation done using DITA methods will allow for single-sourcing for content elements, and equally make it easier to integrate that content into print or digital outputs in a super-organized, modular way. It’s a standard that helps because it’s generic to almost any system out there. Any system that can read XML can read a DITA document, for the most part. When moving from one system to another, the content can stay intact if done using DITA/XML methods.

I don’t remember learning much about DITA in grad school, other than understanding what it was in general as I explained it above. I never learned the details. In my work life so far, I haven’t needed it.  It’s always been unstructured authoring. I try to take some small steps to create some single-sourcing content when possible in content management systems, but that was hard to do sometimes. One of my recent jobs made me realize that we needed some sort of structured authoring done, but I didn’t know how to go about it. We created our own coding tags to describe things going on in copy decks. It wasn’t the best, but it was better than nothing.

In the past year, I’ve tried to figure out ways to continue to improve my skills, and make myself more marketable as a content strategist/content manager. I talked to the leading experts in the field. (It’s one of the benefits of getting involved with the STC and attending STC events–you get to know these people personally.) And the one thing that seemed to come back to me again and again was that I had a good resume, and I have some great skills under my belt, and they knew that I was a good writer from this blog. The biggest sore spot in my skill set was that I lacked an important skill–knowing DITA and using it.  And while I looked for jobs in my area that included DITA practices (I think I’ve only seen one listing in three years), I’ve been assured that if I could learn DITA, the remote/telecommuting possibilities could be much better for me. And since remote opportunities are my best bet right now, I have to do what I need to do to make that happen.

So, as the saying goes, I bit the bullet. Fortunately, the STC was promoting a course about DITA Essentials taught by Bernard Aschwanden, the Immediate Past-President of the STC, and the proprietor of Publishing Smarter. Bernard’s a great instructor, and he’s taking it nice and slow. One of the best parts of the course is hands-on experience, even if it’s in the simplest ways. That’s the way I tend to learn best–learn the logistics of how something is done, then I need to learn to do the work through trial and error.  Last week’s assignment was particularly challenging for me. While I understood what I had to do conceptually, since I was also trying to familiarize myself with a few XML editors at the same time while applying what I wanted to do with my assignment, I got very frustrated. I sent in my assignment, along with notes about where I was getting frustrated and needing some guidance. Bernard assured me that all would be well, and asked me if he could use what I had turned in for my assignment for the most recent class. He also warned me to have a glass of wine ready while taking class, because I’d be needing it. Yikes!

I was told to prepare for the onslaught of big corrections to my DITA homework with a glass of wine. I took the suggestion seriously, thankfully.
I was told to prepare for the onslaught of big corrections to my DITA homework with a glass of wine. I took the suggestion seriously, thankfully.

The glass of wine was done by the end of the class, and yes, he ripped my assignment apart, but it was okay in the end. I knew there were problems with it, and he showed me where my original thought process was correct, but I didn’t know how to execute it properly. One of the mistakes I was making was my use of XML tags, particularly using the correct ones. While the XML editing apps all have guidance features to help you with using correct tags in certain situations, I still wasn’t using the best choices. Most of that was because I’m not familiar with what these XML tags mean, so I was using them at face value. For example, I was using a step example tag in part of my content, and Bernard understood why I used it, but felt that the way I used it was incorrect, and didn’t allow for cleaner coding. Okay, I can deal with that, especially when he demonstrated the correction.

So, as much as I’m struggling with DITA, I do understand the essential concepts behind it now. My biggest problem is learning how to use it beyond the most elementary tasks. I haven’t had any “real world” scenarios to date when I could implement and learn how to use the XML editors and use DITA practices in writing or rewriting content.  I need to figure out how to find content and start having a way to truly play with something so that I can get the full experience of that trial and error to master DITA.

After the STC course that Bernard is teaching, I plan to follow-up with Scriptorium’s DITA tutorials as well, and see if I can learn some more about XML coding. I have a lot to do to figure this out, but I know that in the end, this will be a big skill that will make a lot of difference in how I approach content. The content strategist skills I already have acquired have helped me frame DITA much more easily than if I learned this with no prior knowledge. But, I can tell that I still have a long way to go before I feel that I’ve mastered this.

So, this ends my confession. I have needed to learn DITA.  If it’s not taught in university classes in technical writing, it should be. I think it would have saved me a lot of frustration, and provided more opportunities for me sooner. If I can get a better handle on this, I’m hoping that I can start exploring how XML Editors can integrate with CMSs, like Adobe CQ. I’m not an Adobe AEM developer (I’m not a developer at all!), but I know how to create websites and pages with AEM, and hopefully I can start figuring out how to integrate those skills with DITA skills. I was told by one mentor, that would make me a very desirable job candidate, and I think she’s onto something. Of course, I need to brush up on my AEM skills, since it’s been a couple of years since I’ve used them regularly, but with all things, once you master them, it’s like riding a bicycle. You might be a little unstable at first, but you never quite forget how to do it once you get started back into it again.

Here’s hoping that in 2017, DITA will become a “bicycle” skill for me. I’ll go say a few rounds of the Rosary in the meantime for my penance.

(What do you think? How important is DITA in technical writing? I’ve heard some say it’s a passing trend, and others say that its usage continues to grow. Include your comments below.)


Danielle M. Villegas is a technical communicator who currently employed at Cox Automotive, Inc., and freelances as her own technical communications consultancy, Dair Communications. She has worked at the International Refugee Committee, MetLife, Novo Nordisk, BASF North America, Merck, and Deloitte, with a background in content strategy, web content management, social media, project management, e-learning, and client services. Danielle is best known in the technical communications world for her blog,, which has continued to flourish since it was launched during her graduate studies at NJIT in 2012. She has presented webinars and seminars for Adobe, the Society for Technical Communication (STC), the IEEE ProComm, TCUK (ISTC) and at Drexel University’s eLearning Conference. She has written articles for the STC Intercom, STC Notebook, the Content Rules blog, and The Content Wrangler as well. She is very active in the STC, as a former chapter president for the STC-Philadelphia Metro Chapter, and is currently serving on three STC Board committees. You can learn more about Danielle on LinkedIn at, on Twitter @techcommgeekmom, or through her blog. All content is the owner's opinions, and does not reflect those of her employers past or present.

13 thoughts on “Confessions of a Failed Technical Communicator

  1. I think it’s important for technical communicators to know the principles of structured authoring — things like collaboration and reuse. DITA is the most widely used standard for structured authoring. And it’s cropping up more and more in job postings. So yes: say your Rosary, but first get yourself registered for a DITA class.

    1. I’ve been taking the STC DITA Essentials class for the past seven weeks (last class is today, at the time of writing this reply). It’s been a great introduction, but I want more! I’ll be figuring that out soon enough.

  2. Good post! What Larry said: structuring information starts in the mind of the writer. If you’re working in a group that wants structured content, so much the better.

  3. Hello Danielle,
    As Localization Service Providers (we translate technical publications and software applications), we have been following the rise of DITA and confirm that it continues to gain users. Another strong DITA community is CIDM, which organizes the DITA North America and DITA Europe Conferences.

  4. Good post, Danielle, thank you. Indeed, Bernard Aschwanden is a great techcomm professional and a great instructor. And I agree when you’re saying that “DITA should be taught in university classes in technical writing”. In fact, the University of Ghent has already understood this ( and I have taught some DITA classes there to postgraduate students. It was great fun!
    To me, DITA is not only a standard, but also a methodology, a combination of many best practices in technical writing and structured authoring: single sourcing, reuse, minimalism, writing for translation, information typing… So, regardless of whether you will be using DITA or a proprietary tool in your career, learning DITA is always a good investment.

    1. Thank you, Yves. As I was learning it, and as I’ve tried to describe it to others, I’ve given a similar description as you have–that it’s a methodology as much as it is a standard, and it helps to frame the content in a more organized way than when unstructured.

  5. I have been teaching DITA skills from 2009 in University of Rennes 2: Whatever tool you use, CSS is a great skill to know and fun to test. The W3Schools tutorials can get you started:
    Regarding *applying* DITA, the most efficient exercise in my experience is to migrate a strictly book content to DITA – even a small one or only a part of it. You can learn a lot of what the migration can involve in rewriting and applying topic-based authoring.

    1. Thanks, Nolwenn. That’s good to know! I don’t think that DITA skills are being taught consistently at all tech writing programs. It wasn’t at mine, and I thought I was prepared to go out into the world! I sadly was not in this particular respect, and I’m trying to make up for it now. I like your suggestion for taking a short book and trying to convert it. I think I might try that for practice!

    1. That’s good to know. I’m starting to wonder if it was only my program that didn’t offer something, or if there are other programs that also aren’t offering DITA basics to their student. I had heard of structured authoring, but now I’m starting to question if I first learned about it in my content strategy class, or if I first heard about it at an Adobe Day event. (I’m thinking the latter!). I suppose this opens up a bigger question–are there efforts by the STC or other tech comm communities to somehow provide some sort of standardization of coursework for tech comm programs, so that all tech comm graduates–either on the undergraduate or graduate level–are ensured to have the same or a very similar foundation that includes DITA and other topics that are sought in the real world? I thought I had a good foundation in tech comm, but as the years go on, I’m finding certain gaps.

  6. DITA is not the thing, re-use is the thing. This can be accomplished with DITA or many other ways and tools. DITA is just one method. I think some companies get hung up thinking they need DITA for re-use, when they could get it many other ways.

    1. That’s a great point, Joel. I agree that a big part of it is trying to get people to understand the re-use mentality in the first place. I haven’t had a job using DITA yet, but some of the leading content strategists in the world who I know have been encouraging me to learn it for years. I felt that it was time to “bite the bullet”, and I had nothing to lose. I am glad I did. I’m still learning a bit, but the more I do it, it makes sense, and it can’t hurt my chance when looking for jobs or projects in the future.

Leave a Reply to TechCommGeekMom Cancel reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.