Technical Writing Tools – Do You Need to Know Every Tool?

Have you ever felt yourself becoming overwhelmed with the amount of things you need to learn? Join the club. Since quitting the day job as an employed technical writer and trying my hand at contracting, I’ve been compelled to learn more about a variety of Help Authoring Tools and technical communication principles, ideas, etc.  Like an idiot, I’ve tried to learn too many things in too short a time, and slowly but surely, it has broken me. So I’ve decided to take a step back and consider what are the tools we really need to know?

*Please note that in this post, I’m just focusing on the tools and technical expertise I have experienced in the workplace or seen on recent job ads in the UK, and I have purposely avoided web CMSs and e-learning tools.

Technical Writer Tools

MadCap Flare and Adobe RoboHelp

Hands up, you got me. I’ve never used Adobe Robohelp, despite being a technical author for nearly 20 years. The reason for that is I spent many years working for a company that used alternative help creation tools, including MadCap Flare, which I’m told is very similar to RoboHelp (created by developers who originally worked on RoboHelp, I believe).

But if you are serious about a career in technical writing, you are probably going to need to know Flare or RoboHelp, especially if you work in software.

I am a big fan of Flare. It is easy to learn, has a wealth of features for producing content for different media, and does a pretty good job of single-sourcing. Plus, the MadCap support team are very good, and super-friendly too, which always helps.

I first started working with Flare when I was asked to assess it as a possible way forward when the documentation department wanted to move away from FrameMaker to mif to chm conversions. Using only the documentation provided by MadCap and posts in the MadCap Flare forum, I was up and running in less than a week.  If you work through the PDFs methodically, I’m sure you’ll figure out the basics just as quickly.

Shortly afterwards, I was also treated to a 3 day intermediate training course run by Armada (http://www.armada.co.uk/madcap-flare-training-course), where Matthew Ellison (https://www.linkedin.com/in/matthewellison) ran through much of what Flare has to offer. If you want to figure out how to use Flare to meet your organisation’s needs, I can highly recommend the training course – it is a quick way to learn ‘best practices’. Although UK based, I believe he also does some work for MadCap in the States.

Microsoft Word and Adobe FrameMaker

Yes, there are still plenty of technical writing jobs out there for people who are skilled in MS Word. It isn’t the best tool for creating documentation, but it can be effective and most companies have it, so you will need to know it. And as a technical author, you’re going to be expected to know it VERY well. At the very least, you’re going to need to be able to set up styles , templates, and create indexes and cross-references. If you are not up to speed with Word, there is a wealth of information available online. That’s another reason why lots of businesses use it – most people are competent (to a degree) with Word.

FrameMaker is probably less common, because like most Adobe products, it has quite a hefty price tag. But in companies that have established technical publication teams, you are likely to run into it. If you know Word, adjusting to ‘vanilla’ FrameMaker isn’t going to require a huge effort, with books and chapters being the most obvious and immediate difference. But ‘structured’ FrameMaker is a whole other kettle of fish. For that, you’ll need an understanding of structured writing.

Adobe InDesign

InDesign is more likely to cross your path if you find yourself working on marketing-related material, but is well worth knowing. Designed for smaller, more graphical documents, InDesign makes it easy to create complex layouts. I’m told it isn’t great for longer documents, but I certainly had no problems when using it to create a 60 page manual.

If you know Adobe FrameMaker, you’re going to find it very easy indeed to use InDesign – they share many similar features. But you may need to broaden your knowledge on print-related topics, such as the bleed and slug areas of a page, as these are important when using graphics. Again, there is a lot of information available online and it isn’t difficult to pick up.

Atlassian Confluence

Atlassian Confluence is a popular wiki-editor that is often used for creating technical documentation too. It is easy to use, produces nice-looking online content, and places an emphasis on collaborative work. It gives you a lot of control over who can edit a topic, while also making it easy for people to comment and contribute.

Confluence is pretty easy to pick up (even more so if you know Flare or RoboHelp). A few mornings of working through Sarah Maddox’s book ‘Confluence, Tech Comm and Chocolate’ and I was ready to produce a nice-looking output. If you want to learn about Confluence quickly, I can recommend the book, although much of the content is also covered in Atlassian’s Confluence documentation. One word of warning though – if the inclusion of ‘chocolate’ in the title has already got your alarm bells ringing, the book will most likely annoy you! There are frequent mentions of chocolate recipes and there’s also use of a fictional tech writer called Ganache, both of which got on my ti….er…nerves pretty quickly. But I’m sure it works for some people.

You can find Atlassian’s Confluence documentation at https://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home

 

Structured Technical Writing – DITA, XML

If you look towards the US for trends in technical communication, it is clear that structured content, such as DITA, is becoming more important. Why? Because creating content that uses semantic tagging means topics can be re-used in multiple different outputs and re-used in different tools. You don’t need to be a business-whizz to see the financial gains to be had from being able to re-use the same content, without that content being tied to one particular tool.

What is structured content? Well, it is content that is marked up with code that indicates the type of information. For example, in XML, you could have an author tag for the name of the person that writes each topic. This can then be used in various different ways – you could create a report containing a list of all authors, create a list of topics that were created by a specific author etc. All this is possible because the author tag gives meaning to the type of content.

To write structured content well, you need to know how to write topic-based documentation and you also need to know the rules of the language you are using. This is where it gets tricky, because there is a lot to get your head around and it is easy to get overwhelmed.

I’m only just starting out on my journey into structured content (topic-based writing is no problem, but I’m still a noob when it comes to the tagging part), but I have taken a DITA course provided by Cherryleaf (http://www.cherryleaf.com/training/dita-training-courses-in-london). The training explained how to create DITA content and mark it up, but that’s only half of the battle – if you want to create outputs in different formats with corporate branding etc., you need to know how to configure a DITA plug-in. Believe me, it is not easy, and I’ve since discovered that learning about XML first makes learning about DITA plug-in configuration a less daunting task. It’s not just me, either – take a look at Tom Johnson’s blog articles on DITA and I think you can see that configuring DITA outputs started to bog him down too. (http://idratherbewriting.com/category/dita/).

Is structured writing taking us away from writing and more into coding? Perhaps. But as far as I can see, that is the future for technical communicators. Being a good writer isn’t going to be enough; we need to be able to add value by being more technically capable when it comes to document design, production and publishing.  Don’t believe me? Take a look at this job ad I received only today:

“Our client is looking for a contract technical author to help convert legacy documents created in structured FrameMaker to a new DITA system. You will take ownership of the end-to-end conversion process and take responsibility for delivering an updated document set. You will have: the ability to create and manage topic-based content using DITA; good knowledge of XML; proficiency in a scripting language (e.g. Perl, ANT or PowerShell); experience using comparison tools; good organisational and interpersonal skills to manage the flow of information from contributors and reviewers. “

If you want to learn about DITA, I recommend Cherryleaf’s course and the following books are also very useful:

DITA Best Practices – http://www.amazon.co.uk/DITA-Best-Practices-Roadmap-Architecting/dp/0132480522

DITA for Print – http://www.amazon.co.uk/DITA-Print-Open-Toolkit-Workbook/dp/1937434052/ref=sr_1_1?s=books&ie=UTF8&qid=1402849075&sr=1-1&keywords=dita+for+print

*This book covers editing the plug-in too. I think if you could master this, you’d be in a good position to produce DITA for pretty much any type of output.

Nathalie Laroche has also posted some useful content for the DITA novice: http://www.extremetechwriting.com/learn-dita-on-your-own/

 

How to Learn Technical Writing Tools without Driving Yourself Insane?

Now that is a question I really can’t answer. There just doesn’t seem to be enough time in each day to learn what needs to be learned. What I can do is explain what I tried to achieve, show you how I failed spectacularly,  and then let you know my new plan. Maybe then you can avoid the same pitfalls. Why learn from your own mistakes when you can learn from mine?

When I became a contractor, my first job was working in Flare. I had been working in Flare previously, so there was no problem. In fact, it was at this stage that I first started to look at ways of creating content in Flare and bypassing the skin in the output. (Bypassing the skin opens up your design possibilities, as suddenly your content is no longer constrained by the skin – it is just like any other web page).

But then the next contract came along, and that involved using…Microsoft Word. A backwards step really, but it was good to brush up on my Word skills as I’d not used it professionally in years. But it didn’t take long to grow frustrated with Word and so my quest to learn new things began.

I felt I was getting out of touch with Flare, so tried to convert an old project into Flare in my spare time. That was going well, until I started reading some posts on DITA and that caught my attention.

I’ve always been intrigued by DITA as its underlying principles are, in my opinion, sound, and can really help untrained authors to structure their content more effectively. So I bought some books on DITA and started reading those. Then I took a DITA training course and started to practice with tutorials.  There was a lot to learn, but through doing the exercises, I soon picked up how to create content. But that is only half of the battle – to turn the content into the output you want, you need to customise a plug-in and that becomes pretty heavy work. I soon became bogged down in XML, struggling to understand what exactly was needed.

With work piling up, my learning had to slow for a while. And now I find that I had forgotten much of what I had learned. To make matters worse, I’ve had some e-learning products catch my eye, and now I want to learn about e-learning too.

Needless to say, I am burned out. Too much work makes Jack a dull boy and all that. So here is my plan (and also my advice):

  1. Don’t try to learn everything at once.  Pace yourself, make sure you have breaks and don’t become overwhelmed. You can’t learn everything and if you are not using a tool, you won’t remember it all anyway.
  2. If you are trying to learn DITA, consider reading up on XML first. Creating content in DITA isn’t too hard to get to grips with, but the process of building and modifying your output certainly is. Knowing about XML really does make it easier.
  3. Try not to beat yourself up! Are there many technical authors who know all of the tools and principles of all aspects of technical communication? I doubt it! And don’t forget that there are many writers out there who are resting on their laurels, not making much effort to learn any new tools or methods. If you are trying to learn and improve yourself, that’s always a step in the right direction.
  4. Create an unambitious learning plan and stick to it. An hour a week, a couple of hours a week, whatever you can manage. Just pick a regular time slot to learn something new and remember to make notes (or blog about it).

Now it is time to practice what I preach.

Do you have any good ideas for keeping up-to-date without crushing your spirit? If so, please share below.

About Craig

Freelance Technical Author Craig Wright

I am a freelance technical writer and I can help your business to deliver documentation that helps your customers and reduces your support costs.

How Can I Help You?

If you need help with your documentation, please get in touch. I provide a range of technical writing services and can make sure you deliver content that meets your customers' needs.

FIND CRAIG ON GOOGLE PLUS

9 Comments
  • Thank you, Craig, for an insightful article; “make an unambitious learning plan and stick to it” is what I found missing from my non-work schedule.
    Your article, as you mentioned, dealt with only tools. But, the truth is that irrespective of what tool we use, we are still writers. The expectations from our work have not changed over the years; and perhaps never will. So I was expecting a conclusion that centered on that thought. But, I will still go with your ending, which is more apt in this case.

    • StraygoatWritingServices

      Thanks for your comment, Suyog. I agree that ultimately, we are writers and should be judged on our ability to write and explain. Sadly, when it comes to the job market, certainly when dealing with recruiters, writing ability seems to be an afterthought. The focus of the article was very much on ‘all the other stuff’ we need to know, but perhaps an article on writing or recruiters’ approach to writers would be an interesting off-shoot.

      • They sure are good topics to pen down. I will be curious to know your views on them.

  • Neal Kaplan

    Lots of truth here, Craig. I had a very similar problem when I tried to learn everything about information architecture, content strategy, and web design best practices over the course of a fe months.

    I’ve used all of those tool (except InDesign), but over the course of 20 years. And my Perl coding is pretty minimal, too. That’s a hell of a lot to try to learn in a few months (?).

    As you said, a big problem is that you’re going to forget about any tool that you aren’t using. Of your examples, I think DITA is the most complex. But that’s because you need to learn XML syntax, structured writing (and topic-based writing if that’s new to you), and the authoring tool. Oh, and probably a CMS at the same time.

    There’s also a big difference in effort and time between learning enough to be useful and becoming an expert. I assume that most contracts want an expert, but I try to learn enough to be effective, and then come back and fix my initial mistakes once I’ve learned more. Probably a luxury that a lot of contracts don’t offer.

    And I had the same reaction to Sarah Maddox’s book!

    • StraygoatWritingServices

      Thanks Neal. Don’t get me wrong, I’ve used some of the tools over the 19 years I’ve been in the business (Word, FrameMaker, InDesign, Flare). It was only DITA, XML, Confluence, a bit of JIRA, and a little on e-learning theories that I tried to cram into a few months. DITA and XML is pretty hard-going…I think I would have been better learning that on the job where I could actually use it day-in day-out. I was using oXygen for the XML editing, which is actually fairly similar to Flare in how it looks, so it wasn’t a huge ordeal getting to grips with the basics of that.

      You’d be surprised about contracts (speaking from a UK perspective). Being competent is often all that is expected. I’ve worked for companies where they are quite happy for you to be a novice as long as they can see you are going to pick it up quickly.

      • Neal Kaplan

        I suppose I’ve seen too many job reqs where they want an experienced, multi-language programmer who is also a world-class writer. But if it’s a 3-month contract, I can see how companies would want someone who requires little or no ramp up time.

  • Nathalie Laroche

    Thank you Craig for this very interesting article! ! There are so many tools and technologies that we need to know as technical writers, it’s easy to get lost trying to know them all. And it’s even worse when you’re working as a contractor, because you never know what your next contract might entail.

    I think your recommended approach is very sound. And often just being knowledgeable about a tool/technology (as opposed to being an expert) is enough. I knew a bit about DITA when I was got my first DITA contract, but I was far (very far!) from being an expert. It wasn’t the most exciting contract, but it allowed me to deepen my knowledge enough to find my current (and very interesting) job, which did require a lot of DITA knowledge.

    I also think that you hit on something very important in your article: “And don’t forget that there are many writers out there who are resting on their laurels, not making much effort to learn any new tools or methods.” That is very true. Just trying to stay abreast of the latest developments in the tech writing field will help make sure that we find interesting work.

    Thanks again! (and thanks for pointing to my blog!)

  • swin21

    Quality blog post – I know I’m a bit late to the party, but reading this mirrors so many brick walls I’ve ran head-first into. Plus, it made me chuckle, so never a bad thing. I’m currently nearing burnout juggling learning HTML and Mailchimp with young child and very tired wife for an evening side-project, to help my brother out with a marketing campaign for his micro-brewery business.

    I can relate to having your eye caught by the multitude of new things to learn… I think, that on some level, it’s the fact that your struggling to get to grips with the thing your currently trying to learn. So when something new crops up, it appears very attractive, the grass is greener and it’ll be easier to learn. When your probably just on the cusp of grasping the nettle and getting to grips with your foe.

    We’ve all been in that long-term safe relationship, when suddenly the stunning “my-type” walks in and that’s all you can think of. But the truth of the matter is, your just not happy with your current situation, leaving you with two choices: a). work it out or b). move on soldier 🙂

    • StraygoatWritingServices

      What about ‘Soldier would like to fight in two battles’? 😉

      I agree with your assessment about ‘struggling to get to grips with what you’re currently trying to learn’. That’s true, although it isn’t always ‘struggling’, sometimes it is just ‘I am bored with learning this’. It can be hard to maintain that enthusiasm from start to finish. Often, that’s a problem with the content of the course, where it is too much theory and not enough hands-on doing it for yourself.

      Thanks for posting.

 

More from the StrayGoat blog

See all posts