Online documentation is a special branch of digital life, so when you start any project, like a service or an app, you need it to be well documented. To create online documentation, you need a professional team and a special platform. An example of a tool that’s up to date is clickhelp.com, though there are alternative options. Here is what it has to offer.
Optimization for Various Types of Docs
Source: medium.com
When it comes to online documentation, this term covers multiple types of docs. Not those essential text files formatted in Word as many users think. Documentation usually comes with a marketable product, both for customers to cover the product’s features and for developers to document the process of its creation. Thus, it covers several types of docs:
- Tutorials. In fact, a tutorial is a type of textbook that attempts to cover the entire subject. It has illustrations, media materials embedded, often repeated. The vocabulary through the tutorial should be the same, to avoid any confusion, because customers are not supposed to know all the synonyms, professional slang, or abbreviations used by developers and managers.
- How-to manuals. These are focused on a certain task, so they are shorter but numerous. They also need to be written comprehensively. While any materials (text fragments, pictures, etc.) are rarely reused within the same manual, they can be widely reused across their entire body.
- Discussions. These are less formal, so they can link to formal instructions instead of reciting them.
- Reference materials. These can be used in various forms, including third-party materials that are not supposed to follow the developer’s guidelines.
Obviously, all these documents require a different approach. Everything may vary, from team management to types of editors necessary for creating this or that type. So, we proceed to…
A Decent Editor and Cloud Storage
Everything starts with an editor. Unlike your regular Word, Pages, or Writer, an online documentation tool is more flexible and appears in various versions. It’s logical: if you create illustrations, screenshots, and figures, you need a set of tools that differs from the one the translator needs, and a fact-checker or editor will need an entirely different one. A flexible online editor has all of it: you set up your panels so the tools you need the most are one click away, and those you never need are hidden.
As your document is created, it’s saved on a cloud. After each change, its altered version is assigned the default one while the previous one remains available in the history (like you can see in Wikipedia and other Wiki projects). Access to this document is manageable: some users can only read it, some review and offer changes, and some can actually change it.
There are also specific tasks that matter when you work on a body of documentation, like single-sourcing and content reuse. It saves lots of time, effort, and storage when you need to repeat the same fragments of text and media in multiple documents. In addition, it grants seamlessness and terminology unification. Content reuse can be cross-project due to a shared database and can use variables to produce various forms and versions according to the context.
Document-Based Task Management
Source: medium.com
When you manage some process (and a team responsible for it), you need to control the document flow within. This means that online documents themselves should come with a set of tools necessary for management. Those include:
- To-Do lists within documents that can be assigned to a particular employee or a group;
- Reviewing and editing features that require permission;
- Document sharing (including third-party recipients) with various access levels, from read-only to reviewing and editing.
- Communication tools that come along with these documents, including comments, editing, public and private chats when edited by more than two persons.
- Users receive notifications after the document has been edited.
These tools provide quick teamwork and eliminate any need to involve third-party solutions to edit and share the document as well as discuss any changes and their consequences.
Workflow Management
Source: doforms.com
Any document is a result of collaboration. But who has made any edits, who has read the document, were there any changes after the review, and why did Mr. X or Ms. Y not open it at all while they should have? Overviewing it manually makes little sense and leaves too much to the manager’s will. Instead, this should be formalized by both technical means and established procedures.
There are special procedures known as the workflow that defines who creates the documents, who edits them, who assigns tasks related to this particular document and passes it on, when several versions should be created, and where the final version of this document goes if there is one. Everyone involved should get familiar with these procedures. When followed by everyone, these procedures save time and minimize the risks of something going wrong.
Analytic Tools
Source: forbes.com
If you need a more detailed look at how your working process goes, you need special analytic tools. Which authors contribute the most to the documentation creation? How do you easily count words across the entire body of the documentation? And which texts appear to be the most readable?
Analytic tools work with dozens of metrics and let you rate both the working process and the result of it by various parameters. It goes without saying that, to collect these metrics, the tools should have access to all the logs related to your documents. And this implies that the analytic tools have to be integrated with the platform itself.
FAQ
How do I estimate which resources I need for my company?
Platforms usually offer various plans, so you can forecast your requirements in the future and choose the most appropriate plan. If later your business scales up, you can upgrade seamlessly.
What if I need a third-party specialist who doesn’t have access to our intranet? Can I just share these documents with them?
Yes, and this won’t let them access the rest of your documentation.
Can I switch from one platform to another when the work is already in progress?
Yes, there are usually built-in converters in these systems, so you can export your documentation and then import it to your account on a new platform. There are also third-party migration tools.
As for analytics, isn’t it easier to integrate Google Analytics?
For documents in public access, it makes sense to connect Google Analytics. For internal documents, beginners can be good with Google Workspace because they can have basic services for free, including the Google Analytics addon as well. But a built-in analytic system on an adjustable proprietary platform works with documents that never make it outside your private space. This solution grants much better security and more possibilities.
