We were contacted last week by a SaaS developer who wanted to know if their solution might be of interest to companies needing to write and host their product’s user manual or online Help content. So what capabilities do Technical Authors look for in an authoring tool?
There were a few features that sprung to mind:
- Multi-channel publishing (for example: publishing to the Web, Microsoft Word and PDF). PDFs are still important as a publishing option, as people still like to read good quality printed content.
- Separation of look and feel from content.
- Content re-use (write once, re-use many times). This is different from simple cut-and-paste.
- Variables (so it’s easy to change product names).
- Conditional text (content that can vary depending on the type of user or type of product).
- Link management (being able to find content in the project quickly, as well as being able to manage the dependencies among links and topics).
- The ability to handle larger documents (200+ page documents with screenshots on most pages)
- Expanding/collapsing table(s) of contents (and even different tables of contents for different types of users).
- A user-friendly authoring environment.
- Version management of the content.
Ideally, there would also be:
- A way for occasional users to add and edit content without breaking formatting styles, using a User Interface that didn’t overwhelm them.
- Access to and shared management of the content. This is so that writers could collaborate with each other, working on different topics for publications at the same time.
Are there any other features you would expect?
Some kind of scripting capability to address large-scale changes, or to automate repetitive things. That implies a more general condition than just conditional text.
Conditional pagination for print/PDF output. Come on vendors, troff has had this capability for 45 years now. “Keep with next” is only slightly less lame of a substitute than none at all.
Uptime and reliability, especially in a cloud-based system.
Now for a pie in the sky ask… how about a way to automatically reformat huge tables and graphics for small-screen applications like eBooks?
• built-in support for DITA (my preference) and other structures
• fully-featured regular expressions
• styles! I’m thinking regretfully of failures like Google Docs and Adobe Buzzword …
I’m not so sure about trying to give “occasional users” easy access to a tool defined for/by technical authors; I don’t expect to be able to tweak source code or engineering/production drawings, and my Area Experts are generally happy enough with being able to add comments to a .pdf if they need to show me a remark in context. We’ve also started using a wiki-ish tool with links to documents, so people can call up a document and leave comments/discuss updates.
Ellis, great post, helps to understand who needs what. Based on our experience, different technical writers are looking for different things (sometime the opposite things). For example, a part of the audience don’t really need single-sourcing techniques since they product only one output; others don’t need any exporting possibilities since they product only online versions of their content.
But we are certainly seeing some requests more often than others, here are some of those to add on your list:
* MS Word / HTML / CHM import for existing content migration;
* restricted access to online documentation for readers, with the ability to control who can access what;
* API to include the authoring tool into the existing Continous Integration processes;
* Context Help support to embed help topics and tips into the UI of web applications;
* Web Help output support to host web-based documentation easily in isolated networks or on the same web server as the application being documented.
We need to show revision marks in PDF output so reviewers can distinguish revised or new content from the remainder of the text. Our most formal editorial review is an end to end book review, not a single topic or group of topics.
While selecting an authoring tool for a company, I find it important to know whether it is a startup, or it has just gained traction, or it is relatively higher at the growth curve. It gives me some directions on how much business can invest on an authoring tool, and I can prioritize for the immediate and long-term documentation goals.
Since it is a SaaS solution, I think they would plan to offer subscriptions based custom packages for different sets of features (such as by number of documents, number of users, number of projects).
A few things that I find important are:
– Advanced ‘findability’ options such as by integrating Agolia, or at least AJAX powered search
– Metrics are very important for SaaS, so I would rather use MixPanel and not only Google Analytics
– Integration with online chat services (Olark, Zopim) and helpdesk systems (Zendesk, Freshdesk, Groove)
– Custom branding and advanced control over themes such as to share upcoming webinars (for example, on new features, fixes, support), integrating community content (QA)
– APIs for content reuse such as by InsetPlus
I wrote a related post at idratherbewriting, a few months back. You can see at: http://idratherbewriting.com/2014/12/11/authoring-tools-for-startups-guest-post-by-vinish-garg/