Taking up where from we left off in the Part 1 of the ‘All You Need to Know About Technical Writing Tools‘ series. (Do check it out if you haven’t read it)
In this instalment, we deal with the Technical Writing tools used in the “Document Information” phase.
This is the writing, editing, drawing, reviewing and rewriting phase. This is the phase when the information documentation team is at its full strength churning out guides, manuals, blogs, video demos, online help pages, and what not. Given the variety in the tasks in this phase, the tools employed are also quite diverse, and innumerable.
Let’s begin with one of the most important parts of this phase.
Displaying your product’s online help as wiki pages is a simple and effective idea. Your pages can be integrated into Wikipedia directly if you don’t have a separate website for your online product. Alternately, you can host Wiki like help pages on your product website. High familiarity of this format among online users is a key advantage, and the free wiki editing tool MediaWiki Visual Editor makes help creation quite simple.
MediaWiki is a PHP based web editing tool, which Wikipedia uses. However, even major software corporations, Intel being a key example, use this tool to present their sales and marketing information, How To’s, and help pages on policy and procedures.
Author’s Tip: The tool comes with good support for extensions – for multi-language content, collaborative reviewing, tracking edits, built-in search etc.
Whatfix signifies a paradigm shift in the way help documentation is presented online. Static and lengthy web help pages do not catch the user’s attention as effectively as the interactive, pictorial guides presented by Whatfix, popularly called ‘balloons’.
Moreover, online help in today’s world needs to spread across various gadgets – be it PCs, tablets or smart phones. Whatfix automatically adapts the help content to suit the gadget. And the same help content can be accessed in different forms – as a slideshow, PDF, or a video.
Author’s Tip: Whatfix supports a unique feature – Real-time Interactive walk through – wherein you put your help snippets directly into the live product page! The user reads the snippet in the Whatfix balloon and performs the action accordingly on the page.
Industry standard authoring tool used to create help systems for desktop or web-based applications. No computer user is a stranger to RoboHelp! Every time your press F1 in any of your standard software applications, the help window that appears is almost always created using RoboHelp. However, it can also be used to churn out conventional technical documentation for print, such as guides and manuals.
The sophisticated RoboHelp IDE enables technical writers to develop large scale help projects and render them on multiple hardware devices/operating systems, and in multiple formats (PDF, HTML, DOC, etc). Older version of RoboHelp can be purchased as a low cost edition, if budget is a constraint. However, small companies can stick to simple, free alternatives such as WordPress blogs or Wikis. Good old MS Word also can generate basic HTML help files for you.
Author’s Tip: Managing large software products with regular upgrade versions can be a major challenge for technical writers as they have to be in sync with the product change history. Help files often show configurable user defined variables that are repeated several times throughout the help documentation. (For example: A variable such as “Sleep time after inactivity” is set to 30 sec in the previous version, to be set to 1 min in the upgrade.) The RoboHelp project would take care of updating the variable value throughout the help files!
A very effective beginner’s HTML editor. Most people learn basics of HTML programming on this tool. If your software product does not require very heavy online help documentation, for making help files of medium size, this tool is more than sufficient.
Its customizable GUI allows for easy editing, it supports WYSIWYG for printing, and also has multi-language support options.
Author’s Tip: Notepad++ comes with a rich set of plug-ins. Multi-clipboard, Code Compare, Auto-Save are some popular ones. Technical writers need to pick the right set of plug-ins, which can transform an ordinary beginner’s editor to a viable option for online help editing.
The GoTo place if you want to have technical documentation for your product in the form of blogs. WordPress is an open source , free, online content management platform. Blogs written on WordPress can either be accessed directly from the WordPress blog URL or can be integrated into your company web-site.
This article itself is hosted on the WordPress blog called Whatfix Academy. If the goal is to publish online content about your company/ associated technologies regularly, then setup a WordPress blog account. Blogs can also capture user responses in the form of comments and likes, which makes it easier to engage with your target audience and sense their appreciation for your product.
Author’s Tip: Blogs in isolation may not gather sufficient eye balls. So, write your blog first, promote your blog on social media platforms next and finally measure the viewership / responses before getting on with the next set of blogs!
One tool which most technical writers across the industry swear by. It is the world’s most popular image editing tool for creating and editing photos and raster (pixel) based art work. Can be used to create User Interface designs, Web pages, Banner ads, Video graphics, Editing pictures for print. Manipulating an image, superimposing one image on another, refining a photograph to iron out imperfections, correcting lighting issues are its most popular uses. Image editing process is reversible and incremental so that changes can be rolled back easily.
Author’s Tip: For professional designers, who are constantly in need of an image editing tool, there is almost no replacement to Adobe Photoshop. However, if you are an occasional user, try GIMP which is open source. It does support only RGB color schemes whereas Photoshop also supports CMYK (CYAN YELLOW MAGENTA BLACK) color mode. And the learning curve is higher for GIMP, but its free while Photoshop costs a bomb!
Tool for creating and editing vector based illustrations such as logos and brand marks or other design elements. Graphic designers often make the mistake of designing their product logos on Photoshop. But the same logo needs to be printed on visiting cards, as well as massive advertisement bill boards. So, image scaling without losing the clarity is the key here, which vector graphics based imaging tools achieve. Adobe Illustrator and Corel Draw are the leading tools in this space.
Author’s Tip: This tool is part of the Adobe Creative Cloud solution with expensive monthly rentals. Free alternative tools like Inkscape or Affinity Designer can do the job equally well with SVG formats. Unless you require all major tools that part of this solution (Photoshop, InDesign, etc), this tool is not a must have.
Popular diagramming tool used in engineering applications design. Technical writers often need to design flow charts, architectural diagrams, electrical circuit diagrams, software product design and so on. Visio is a convenient aid for this.
It is an IEEE compliant tool that conforms to software industry standards such as UML (Unified Modeling Language) and BPMN (Business Process Model and Notation).
Authors’ Tip: Visio has not been part of the traditional Microsoft Office suite, has always been sold separately similar to MS Project. But a very recent announcement from Microsoft says that online subscribers of Office 365 can now access Visio also.
If you are looking for screen capture options that are more sophisticated than PrntScr on your keyboard, Snipping Tool is a good choice. Apart from full screen capture, you can also capture free hand crops, or partial screen area crops. To capture still images from videos, use the delay option so that the exact frame can be saved as an image.
Authors’ Tip: It is part of the Windows suite of software, but may not be enabled by default in some editions of Windows.
A simple video editor tool which technical writers can use to make their product demo videos. It is part of the Windows Essentials suite. However, since January 2017, this software has been discontinued, without announcement of a proper replacement. So, all those users with older Windows versions, thank your lucky stars!
Authors’ Tip: Videos and audio clippings can be arranged and edited on a storyboard view, frame by frame. Or a series of still images can be stretched on a timeline. Audio voice overs meshed with background sounds can give your videos a sophisticated edge.
Technical writing is increasingly becoming visual. Animated videos are an excellent way to capture user attention and pass on the message in an engaging way. Powtoon is a good web based animation tool, sold as a SaaS product. Animated presentations and explainer videos can be created using this tool for free. However, the videos created with the free version would carry a ‘Powtoon’ watermark.
Authors’ Tip: If the technical writing is not for official purposes, it perfectly OK to use the free version of this tool. However, a nominal rental, you could get the premium version which allows you to create videos without the watermark, and several other features.
An unconventional take on making demos in the form of a video presentation. Unlike Powerpoint, where content is rigidly divided into slides, Prezi gives you just one massive blank canvas. You can go about writing, drawing on it as you please. Zooming in or out of the content in focus and shifting focus from one frame to another on the same canvas – is how you make a continuous video presentation.
Authors’ Tip: Apart from the free version, there is a student trial version that is also free which has almost all the features of the paid version. Pick that one.
It does feel rather silly to write about the ubiquitous MS Word. But however commonplace it may be in our daily digital lives, it still happens to be the best friend of a technical writer! With easy conversion between PDF and DOC formats, the simple combination of Word and Adobe Acrobat Reader is not to be taken lightly. This article might be about all the fancy tools in the world, but it is being written using – the humble MS Word!
Authors’ Tip: Experiment with the various document templates that Word has on offer. They help to make your document look appropriate for the purpose intended – as marketing flyers, technical whitepapers, trouble-shooting guides, and so on.
MS Word, PowerPoint and Excel are known to be the most used software tools, miles ahead of alternatives available. Only the Android revolution has slowed down the MS Office juggernaut a little. And given a position of prominence to Kingsoft Office, a reasonable and free alternative to MS Office.
Authors’ Tip: There are a few nuanced features that WPS Writer does not support – Thesaurus being one of them. Thesaurus is an important feature for technical writers as we are constantly looking for better words to express the same points in different technical documents!
In a world that is increasingly turning to a handy mobile phone to read documents, rather than take the trouble of powering the computer on, google docs in slowly gaining prominence. Creating documents from scratch would not be convenient on Google Docs, but collaborative review and editing can be done efficiently through this cloud based alternative to MS Office.
Author’s Tip: Its seamless integration with Gmail and Google Drive makes it even more attractive. As a technical writer, you would stick to the sophisticated word processing tools. But your product manager who might be on the move all the time, is sure to catch up on his reviews on his phone, in all probability!
A sophisticated document processor for large, industrial standard documents. Can be used to generated structured documents with an XML framework, with 100% DITA compliance. Can be used for unstructured documents as well, as a replacement to document editors like MS Word.
Framemaker is a good choice for generating structured documents with pre-defined templates to comply to several industrial standard formats – such as legal agreements and financial statements. It supports TOC or index creation across multiple documents, has rich formatting options. Does not sag in performance when graphics are inserted.
Author’s Tip: Framemaker is a sound investment for established companies with formal technical writing teams that need to produce large documents of over 100 pages. However, single product companies and startups need not make this investment. There are free tools XML based document authoring tools available for free. And you can always fall back on good old MS Word!
This is a free, open source DITA compliant XML editor, with several loyal users and good reviews. DITA (Document Information Typing Architecture) is an open standard for document authoring and publishing that has slowly made its way into technical document management. Simply because it removes the dependency of editing content on a particular tool. You churn out DITA compliant online documentation (a set of XML files), then editing and maintaining it in future would be possible through any other DITA compliant tool!
Since DITA specifications is an area that requires special focus, let me save that for another article.
Author’s Tip: Suffice to say that oXygen suite of tools is a viable alternative to the hugely popular but prohibitively expensive Adobe Framemaker. oXygen Author is generally used in combination with oXygen Developer.
So, that’s all the Technical writing tools that you’ll need in the “Document Information” phase. The next and the last part will feature the “Publishing the Information” phase.
To make sure that you don’t miss it, subscribe to our blog.
Like it? Bookmark the article or share it with your friends and colleagues!
We at Whatfix, are innovating the Technical Writing space by disrupting the very idea of lengthy continuous written content. Our interactive guides will help you become more productive by providing you a quick and effective way to create Technical Documentation. Read more on how Whatfix helps in technical writing in this article.