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 define their documentation requirements. Though I felt that I could have done this for them, I wanted to hear what they felt was important.  I thought it best that the company representatives initiate the list because they were more focused on what they thought was important, rather than the tools that might meet these challenges.

Once they had defined their requirements, I adjusted the lists to the realities of various solutions and created a chart for each company that mapped their requests to industry-standard terminology such as single-sourcing, scalability, mobile outputs, etc..

Though the discussions were quite extensive and the list included explanations as to why each element was a requirement, following is a concise list per company.

• Company A:
  • Required options: PDF, Web-based help, mobile formats
  • Branding of PDF and help documentation for corporate look/feel
  • Allow commenting by engineers
  • Ability for the company to modify and publish content
  • Industry standard tool with potential for an easy exit in the future
  • Support for SharePoint
  • Price is a major consideration (company is currently using AuthorIT and has old RoboHelp licenses that it might be able to upgrade)
• Company B:
  • Required options: PDF, Web-based help, possible knowledge base
  • Branding of PDF and help documentation for multiple end-customers
  • Support for translation management/localization
  • Solution must be scalable to handle large projects
  • Solution must be able to share content across locations in a shared repository
  • Teams from multiple international locations must have access to the repository
  • Allow commenting by engineers
  • Ability for the company to modify and publish content
  • Industry standard tool with potential for an easy exit in the future
  • Support for SharePoint and version control
  • Price is a consideration (the main company has not invested in any documentation tool; the daughter companies have all gone with free solutions such as Doxygen and LaTeX)

As we reviewed the list of requirements, I did my best to explain why some of the requirements were more critical or less critical from a documentation point of view. For example, any realistic solution is going to allow for single-sourcing and therefore I felt specifying it as a condition was unnecessary. I quickly realized that what I took for granted as a standard feature for all current solutions, was considered to be a major reason for upgrading from their current documentation tools.

While I knew that all options I offered would meet this requirement, I also realized that the company representatives needed to see this on their list and so I left it there. At the same time, I deleted other “obvious” options such as the ability to import graphics and the ability to customize fonts, colors, etc. After modifying and finalizing each company’s list, the next step was to examine the options for potential solutions and map each solution’s features to the Requirements list that we created with each company.

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