Help authoring tools (HATs) refer to software applications that help companies create, manage, and publish a large amount of documentation for their users or employees.
As such, they can be used in various industries, but we’ll focus on the most typical use case—producing end-user and developer documentation for software and other tech products.
HATs are popular among tech companies because the nature of their products and services—and the processes to develop them—requires comprehensive and often complex documentation to be presented in a clear, well-organized, and user-friendly manner.
To do that efficiently and cost-effectively, companies often look for a single HAT to cover all their documentation needs.
They need a solution that integrates all the key features technical writers, developers, and other stakeholders need to collaborate to create high-quality documentation.
So, here are the top eight features such a tool should have.
Easy-To-Use Editor
Whatever the type, purpose, and final format of your documentation, writing and editing it is the first step.
That’s why every help authoring tool should include an easy-to-use document editor with various options and shortcuts that help technical writers, developers, and other subject matter experts (SMEs) quickly create and edit any type of documentation.
You can think of a document editor as a kind of word-processing software akin to MS Word, but with serious upgrades.
In other words, this critical HAT feature should allow the documentation writing team to:
- create and edit content using a familiar word-processing interface
- use standard formatting options such as bold, italic, underline, and bullet points
- add images, tables, and links
- use predefined styles and templates to ensure consistency in formatting and layout
- use shortcuts to speed up the editing process
Editing tools like that usually rely on Markdown—the most popular formatting language for technical documentation—to create high-quality content that is easy to read and navigate.
In addition, it’s also useful when writers and developers can use the editor to insertcode snippets to illustrate their point.
More precisely, writers and developers should be able to create and edit code snippets (syntax highlighting, auto-completion, error checking) in multiple programming languages, including JavaScript, Python, Ruby, and more, and use the editor to insert those snippets into the document.
Beyond that, a user-friendly editor should offer advanced text and code formatting options like code blocks, headings, andin-line comments, as well as allow documentation creators to customize its layout, font size, and color to suit their preferences.
Given its content creation purpose, an easy-to-use editor should provide a range of other text editing features.
We’ll cover some of those in separate sections, such as drag and drop, import and export, and collaboration options, with the latter being arguably the most important.
Overall, an easy-to-use editor—a critical component of any help authoring tool—should provide a simple and intuitive interface that allows teams to create, update, and edit the content of their documentation effortlessly.
Drag and Drop
In a document editor, drag-and-drop works like cut-and-paste. Users can easily grab external images, files, and other content and drop them wherever they want in the document.
Of course, they can copy and paste both external content and internal elements using keyboard shortcuts (Ctrl+C for copy; Ctrl+V for paste) or the editor’s hovering bar.
However, the drag-and-drop feature is equally useful for organizing a clear and logical structure of all documentation.
In other words, the help authoring tool should enable writers to quickly and easily organize their documentation by simply clicking on documents and moving them around to create document trees similar to this one.
This feature allows documentation creators to create a clear tree-like structure (i.e., a table of contents) that ensures readers can easily find the information they need.
To do so, the authors don’t have to manually rearrange underlying documents and files but just drag and drop a heading or subheading where they want in the document tree.
Naturally, using drag-and-drop speeds up the documentation structuring process, i.e., saves time and increases the efficiency of document creators.
To summarize, this simple feature allows documentation creators to—on the text editing level—add images and files to their documents and move their internal elements with ease.
On the documentation structuring level, it enables them to quickly create well-organized and easy-to-navigate documentation hierarchies.
Import and Export
Another critical feature for any help authoring tool is the ability to import and export commonly used file formats, allowing writers to transfer files between different tools without the need for manual conversion.
In other words, the import/export feature acts like an automatic all-in-one file format converter you would use to, for example, create a PDF from a Microsoft Word document or convert a JPG image to PNG format, and vice versa.
In the context of creating software documentation, the benefits of this HAT feature for document creators are versatile.
For example, companies that already have documents in different file formats can simply import the existing content into their HAT, and writers can begin working with it immediately.
In such cases, the import feature is a great time-saver.
The automatic conversion of the supported file types ensures the preservation of the document’s original formatting and structure, thus eliminating the need for time-consuming and annoying reformatting.
For instance, you can import an existing Markdown file with contents of your documents into your HAT and easily create a documentation site in HTML format.
The export feature is equally valuable, particularly when content creators need to share their work with clients or collaborators who are not using their HAT.
By exporting the document to a commonly used format like PDF or Markdown file, the writer can ensure that both the client and external collaborators, such as freelance writers and contracted SMEs, can access and read the content without any compatibility issues.
This also comes in handy when you need to print hard copies of some documents, whether for reference when offline or as part of the package your tech product is sold in.
In summary, the import/export feature provides document creators the flexibility and freedom to seamlessly work with different file formats and tools, thus saving them time and effort.
Access Control
This critical feature l protects the security of sensitive and proprietary information when creating and managing technical documentation, prevents unauthorized access, and minimizes the risk of unwanted modifications or deletions.
To ensure this, the access control feature should offer public access control and role-based access control.
With public access control, you’re ensuring that some parts of your online documentation database (i.e., knowledge base) and the information in them can be accessed only by authorized individuals.
This is particularly useful when you want to share some—not all—of your documentation with outside parties involved in creating, managing, or updating documentation (freelancers, SMEs) or interested parties such as investors, partners, and potential clients.
Public access control can be ensured in several ways, for example, by sending the authorized user a magic link they can use to access specific documentation.
As you can see, this feature can offer multiple options, such as setting a password, creating a guest account, or even methods with added information security like JWT (JSON Web Token).
Now let's turn to role-based access control.
Since the documentation creation process typically involves multiple contributors, the team manager can set different permissions for team members based on their roles, ensuring that each has an appropriate level of access to the documentation.
For example, the manager may use the HAT to assign users roles such as "writer," "editor," and "reviewer."
In this case, the writers will have the ability to create and edit content, the editors will have the ability to review, make changes, and approve the content, while the reviewers will only be able to view the content and provide feedback.
This minimizes the risk of unintended changes or deletions occurring in the document creation process.
Overall, access control is a critical feature of a help authoring tool, allowing companies to maintain the integrity and safety of their documentation while enabling access to relevant internal and external stakeholders.
Collaboration Options
Since no software documentation is created by a single writer but is generated by the efforts of multiple different contributors, the options provided by this HAT feature are crucial for enabling real-time and asynchronous communication and collaboration between all involved stakeholders.
For collaborating in real-time while creating documents, users can—in most help authoring tools—communicate using a built-in chat feature.
That way, team members can exchange messages, files, and links without leaving the HAT environment and jumping over to, for instance, Slack.
For collaborating when not in sync—meaning when they’re not working online simultaneously—team members can leave comments in specific document sections, making it easy to track feedback and changes.
For example, our help authoring tool and documentation platform, Archbee, offers both real-time and asynchronous communication and collaboration options that will ensure efficient teamwork in creating documentation, regardless of the team members' locations or time zones.
Given the importance that quality teamwork has for producing quality documentation, collaboration options are an essential element of any useful HAT.
Document History
Document history allows team members and other contributors to track all edits made to a document and restore the document to a previous version if necessary.
This is a common feature of many HATs going under different names, such as version history, audit trail, or changelog, but with one common purpose—to track who and when made changes and what those changes were.
However, this handy feature will also keep old versions of documents on file, thus preventing accidental loss of important information from version to version.
It also allows you to review and, if required, revert to any previous document version.
The document history feature will also highlight the changes made in different versions, which minimizes the risk of unintended changes or deletions.
As you can see, Archbee’s document history feature also shows which team members made the changes, which lets you establish a clear record of accountability for documentation edits.
To sum up, your HAT’s document history feature is a critical tool for tracking all document changes, preventing information loss, and establishing responsibility in the document creation process.
Backup and Recovery
The backup and recovery feature works a lot like the document history feature but on your HAT’s system level.
This feature ensures that all data stored within the tool is backed up regularly to prevent data loss in the event of system failure or accidental deletion.
On the document level, if the system crashes or internet connectivity is lost, the user might lose any unsaved changes in the document.
In that case, they can access the document history—data backed up by the HAT—to find the last saved version of the document before the crash and restore it with a single click.
The same applies to the system level, where a glitch can cause part or all of the documentation stored within the tool to disappear.
As you can see, Archbee has got you covered, even in such unlikely cases.
Another use case when backup and recovery can be crucial is when accidents occur outside the text editor, for example, if someone deletes the entire project in their HAT.
If the HAT automatically backs up all data stored within itself on a regular basis—as it should —they would be able to recover the deleted project by accessing the most recent backup.
Simply put, this critical HAT feature provides peace of mind to teams working on important documentation projects, knowing that their work is safe and can be easily recovered in the event of any unforeseen issues.
Integrations With Other Tools
By now, it’s obvious what a powerful ally an HAT can be in creating, managing, and updating documentation.
However, employees and external associates of a typical software company will naturally use various other software tools for software development, project planning, scheduling, management, communication, and so on.
For this reason, HAT is even more powerful when it can be easily integrated with other tools writers and developers are already using, such as Google Docs, GitHub, Jira, OpenAPi Swagger, or Trello.
When your HAT offers such integrations, you can easily connect the systems and use data and materials from those tools within your documentation.
For example, these are just some integrations provided by Archbee:
We already mentioned another case when built-in integrations are crucial: when a software company wants to move its existing documentation to a new help authoring tool and/or knowledge base.
Overall, convenient integrations with other tools—an integral feature of an HAT—enable seamless collaboration between writers and other company functions and make it easier for companies to streamline workflows, ensure consistency of information, and save time.
Conclusion
Now that we’ve covered the top eight features of HATs—from an easy-to-use editor, through security and recovery options, to integrations—it’s clear that those tools help companies and their writing teams produce comprehensive yet concise and well-organized technical documentation.
When these features are found under one HAT, they streamline the documentation process and allow companies to create high-quality documentation that is easy to manage and maintain, thus improving the quality of your end-product.
