How to Publish Online Documentation That Works

In my previous article Role of Technical Documentation in Your Business, I promised to talk about publishing your online documentation and how to make it work for your company. So. let’s start by contemplating why online documentation is a must in today’s realities.

If you’re a big company with offices worldwide or a small business with a few employees, either way, you need a procedure to store and manage your documents online to go with the tides. The correct system will keep the client’s information protected while also making it easy for employees to collaborate. While basic paper file systems may have been effective in the past, simply storing your files in a metal cabinet in the corner of the room won’t cut it in the digital world. If you didn’t think about switching to an online document management system, now it’s about time! Because of:

  1. Collaboration. In many cases, working with paper copies doesn’t promote collaboration. Email can result in duplication of efforts due to everyone independently making their own changes and then sharing them with the group.
  2. Productivity. Productivity is what can be hampered when sharing files via email or as paper copies. Editing gets complicated with more than one person involved. In the case of paper editing, someone should be responsible for putting changes to the electronic version — which is not an efficient system.
  3. Flexibility. Traditional file storage solutions can be limiting — if you’re not in the office, you don’t have access to the documentation. With an online documentation tool, business is more flexible, and workplaces aren’t tied to traditional office settings: you can access your documents whenever and wherever you need them and log on from multiple devices.
  4. Permissions. It means you’ll want to have a system for permissions. All files should be shared securely, and you should have the ability to monitor who is accessing files and when.

Numerous businesses are suffering from huge financial losses due to the unwanted waste of time and money in workplace management. But today, you can avoid such office hazards by switching to an online documentation tool.

Things to Consider When Publishing Online Documentation

  1. File format. HTML is an obvious choice for publishing online help. In that case, your documentation will consist of HTML files, image files, and JS (JavaScript) files. In some help authoring tools (HAT), this format is called web help. Some tools generate online documentation with HTML5 elements. You can also upload your documentation to your website in one file, for example, in PDF format. If you do it, the users can download that file and then view it offline almost on any device, and it also will be easy to print out the whole document.
  2. Navigation. The users rarely read online documentation from start to finish. So it is essential to indicate the current section with the position of that section in the whole documentation. Also, show related sections and recommended pages. This is done with good navigation in your documentation. Add links to the next and previous pages, especially if the table of contents is very big. Thanks to linear navigation, the user doesn’t have to look for the current topic in the table of contents and then try to understand which topic is the next one.
  3. Table of contents. The table of contents (TOC) should be easily accessible from any page of your documentation. It shows the document structure and the position of the current section and lets the user instantly go to other sections. Never make the table of contents a separate root page in the documentation. In that case, when the user wants to switch to another section, the only way is to go back to the root TOC and then select the necessary section there. That’s inconvenient.
  4. Subsections. Put a list of related sections (“See also”) and a list of the current topic’s subsections at the bottom of each page. So, the user can easily find additional information related to the current topic without using the search functionality.
  5. Search. Search functionality is important in documentation with multiple pages. You can implement search by relying on third-party tools, such as Google Site Search, or by using self-made scripts. However, if you use a professional HAT tool to create your documentation, you usually get that functionality out of the box. You don’t have to configure the web hosting, connect a database, or add some scripts on the server-side.
  6. Branding. A user should see what the project or a company is when reading your online documentation and switch from any page of the online help to other sections of your site. Documentation pages should contain your website’s main menu and the elements of your corporate style, such as a logo, contacts, or slogans. It would be nice to use your website’s header and footer on the pages of your online help. Use the same styles for the online help titles, links, and paragraphs as on your main site. This way, the documentation pages will look just like your regular website pages.
  7. Location. Put the online help files into a separate directory on your product site. So it will be easier for the users to access the documentation and easier for you to maintain and update it because the help files will not be mixed with the files of the other sections of your site.

Following these principles is very easy. Bearing them in mind, you’ll be able to create online documentation that is not just a bunch of boring texts but a powerful tool for enabling technical support, communication with users, and promotion of your project in the market. Specialized help authoring tools like ClickHelp can solve the technical problems for you so that you can focus on the most important things — your users and your documentation.

Stay well!

Amrit.

“Follow the river and you will get to the sea.”

Passionate technical writer