There are a few questions that constantly bog the minds of technical writers.
– Are there any suitable technical writing tools for the task I am presently doing? Something that would minimize my efforts and produce better quality output?
– Can my company afford it?
– Is it going to be easy to learn how to use the technical writing tool?
Technical writing is as much about the human documentation effort as about identifying the right tool to invest that effort in. Gone are the days when MS Word was the ‘Be All and End All’ of software tools available for documentation. Today technical writing has morphed itself into demo videos, e-Learning mobile apps, online Wiki pages, interactive media, blog posts, and so on. Of course, the traditional FAQs, installation guides continue to thrive.
In such a diverse space, it is natural for several efficient and cost effective technical writing tools and technical writing software to evolve. But for a technical writer to pick the necessary ones and avoid investing time and money in frivolous ones is the key. While scouring the internet as part of the research for this article, I found that there was no single place a newcomer could go to, in order to figure this out.
So, this article endeavors to fill that information gap. You might find answers to the questions listed above. Apart from that, you would find a ready reckoner of the following:
– What are the different aspects of technical documentation.
– What are the different tools available for each of these aspects of technical documentation.
– A Quick comparison between similar technical writing tools.
– Product Versions and Pricing options
– Authors tips and recommendations on each tool.
That’s right. Just like a software product passes through various lifecycle phases, so does the technical documentation that accompanies the software product.
Any software product can be seen taking shape from the ideation and planning phase, then progressing to the product development phase and finally reaching the product delivery phase. Similarly, the INFORMATION DEVELOPMENT LIFECYCLE can also be roughly divided into the following 3 phases:
In this phase, we identify the various documentation requirements of the product. We identify the potential document users and their key use cases. Once the list of documents is ready, we then proceed to plan the overall structure and layout of each document. A good information architecture is a key supplement to the main product architecture. This phase is mainly the responsibility of the product design team. Technical writers may not have the macro level product vision to handle this phase. Naturally, tools used in this phase are more design/modeling tools than technical writing tools.
Part 1 below – Technical Writing Tools for the “Gather 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 of the tasks in this phase, the tools employed are also quite diverse, and innumerable.
Part 2 coming soon – Technical Writing Software/Tools for the “Document Information” Phase
By now, the information content is ready. The generated content must now be delivered on the appropriate platforms to maximize viewership and smoothly integrate with the original product. Whether in the form of a printed manual or an online blog or interactive visual guides, the medium decides what associated tools are necessary to be used.
Part 3 coming soon – Technical Writing Software/Tools for the “Publish Information” Phase
The list of technical writing software encompassing these 3 phases is rather exhaustive to compile at one shot, and readers are also likely to face ‘tool fatigue’. So, I have divided the entire article on technical writing tools into a 3 part series – each part focusing on tools belonging to one phase at a time. Some tools are versatile and can perform tasks covered in more than one phase.
If you are employed as a technical writer in a large corporation, it is quite likely that the system architect of your product is already using Rational Rose as a UML modeling tool. For capturing documentation requirements and tracing use cases to specific user actions, UML (Unified Modeling Language) is the de facto industry standard.
Author’s Tip: Information requirements must be treated at par with other product requirements. So, it is a good practice even for small companies to use these formal architecture and design methods. However, Rational Rose is prohibitively expensive. Free tools like StarUML are perfectly acceptable alternatives.
StarUML is an open source UML modeling tool that enables you to generate use case diagrams, activity diagrams, etc for modeling the information documentation features of the product.
Author’s Tip: Information requirements do not require the full feature set of sophisticated tools like Rational Rose. StarUML supports almost all UML 2.0 features, adequate for technical documentation features.
Software products in today’s world are by and large meant for online use. So, gathering statistics on the internet traffic that your product website generates is a key step to determine its success or reach. This also applies to associated online documentation supporting the product in the form of blogs and wiki pages. Google Analytics helps you understand user behavior. Also, you get an edge if you are familiar with building a solid user onboarding process.
Companies like Adobe, Microsoft are known to constantly revise their online documentation based on user statistics collected on a geographical region of users visiting, devices used to access documents, errors reported, etc.
Author’s Tip: Online documentation must be regularly updated and revised based on reader feedback and visitor statistics. So, periodic reports generated by the Analytics tool can give you an insight on where are the improvement areas.
Search Engine Optimization is a relatively new area of focus for technical writers. With blogs and wiki pages taking center stage in product related documentation, ensuring that the blogs receive high viewership and visibility becomes an added responsibility. Having a sound knowledge of user onboarding tools also helps.
Ensuring the title and keywords in the article are easily ‘searchable’ by search engines, building cross references and links between various web / social networking platforms – are a couple of simple SEO techniques. Free SEO tools by Moz can aid in this process of fine tuning your online document content.
Author’s Tip: Focused SEO support can be obtained by subscribing to paid SEO tools. However, a good many of the standard recommended tasks can be done by the product team themselves. So, it is simple a case of effort vs cost. However, basic SEO support can be obtained from free tools.
Research papers and technical whitepapers are critical works of technical writing. However, they are not authored by the average technical writer, but by the product designers themselves.
Zotero is one such free, easy-to-use tool to help you collect all your research in a single, searchable interface. You can add PDFs, images, audio and video files, snapshots of web pages, and really anything else. An indexed library of your entire research material is maintained for quick referencing and documentation.
Author’s tip: Technical research documents could contain protocol specifications, API documentation for software modules or hypothesis-driven scientific research results. Using the right tools to collect, organize, cite and collaborate research work might save a lot of time and effort.
So, that’s all the tools that you’ll need in the “Gather Information” phase of technical writing. The next article in this series will feature the technical writing tools for the “Document Information” phase and that’ll follow with “Publishing the Information” phase.
To make sure that you don’t miss it, subscribe to our blog.
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.