Blog

More in the series: Choosing a Tool

For many years, I have worked with hi-tech companies, creating their documentation and/or online help using a variety of industry-standard tools. In recent weeks, two companies have asked me to help evaluate their current and expected future needs to
determine the best tool for them.

I felt it was important for each company to understand their current documentation practices. While technical writers may understand the implications of certain decisions, most other company employees (engineers, product managers, C-level, etc.)  are more focused on what is delivered than on how long it took and how efficient the process was in getting there.

• Company A: Was moved into AuthorIT to document their small product line. They were unable to create the documentation themselves, requiring external help, even for the most minor changes. They currently have no need for conditional text and didn’t really understand much about the concept of single-sourcing, despite having their files in AuthorIT.  Reviewing the files after the external writer delivered an update was time-consuming and very expensive. For two small documents, the company estimated that it had spent tens of thousands of shekels and was very upset about the process and the cost. They have no technical writers in-house and have no intention currently of bringing in a dedicated writer, but they do have a team of engineers that they wish to have maintain the documentation once it is ported to an application or solution they can use. The team is all local to northern Israel and they want a solution requiring no (or minimal) external help.
• Company B: Is a company that has grown substantially in the last few years. They have a base solution and have acquired three additional international companies in recent years that have developed products that enhance their core technology, From a single team in central Israel with a sales department and support in the US, Asia, and Europe, the company now has four development centers. They have a single technical writer in Israel while the other companies have, until now, relied on their engineering department to  produce documentation. One chose Doxygen while the other chose LaTex – both free tools. The current situation finds them with a five development sites, one technical writer, three product managers, 6 major contributors and up to 30 engineers that may be asked to comment on sections of the documentation. It is estimated that the company has as much as 2,500 pages of documentation in PDF and html-based formats. It has a knowledge base for internal use and an active marketing department. Many of their documents contain text that has been copied and pasted from other documents. Usually when they develop a new product or service, it is based on their existing technology and results in changing the core product as well as some of the related features. Often a single new feature can result in having to modify as many as 15 other documents.

After explaining the current situation to each company, I thought it important to define the requirements – both current and future – for which we must find a solution.

I explained that often finding the ideal solution is as simple as ruling out the options that don’t meet existing requirements.  For example, while FrameMaker is a fantastic, stable single-sourcing option, it does not, by itself, generate html-based documentation. Therefore, in both these cases, FrameMaker could not be considered the ideal single tool for which they were looking. So, the next step was to agree on a list of requirements and to even prioritize them. What should be considered “a must,” what is “very important,” and what requirements aren’t really requirements but rather fall into the area of  “nice to have” etc.?

To continue the series, see Choosing a Tool – Defining the Requirements  (Part 4) – coming soon…