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.

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/2014/04/16/my-dita-journey-begins/).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/0132480522DITA 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.