After finishing a few technical documentation projects, I would like to share my impressions about various documentation writing and hosting tools.
ClickHelp has not struck me in the beginning. The visual design of a sample project was quite flat.
But later I found out that it is possible to upload a CSS file to align your documentation’s design with your corporate design and branding.
I completely fell in love with the sidebar where you can move sections around: up and down and between different hierarchy levels. It allowed me to restructure the documentation easily and polish the outline till it was close to perfection. A well-structured outline is a great deal for users that do not have to search through it for ages.
As a revision tool, ClickHelp beats a lot of its competitors. It has integrated document history, a commenting feature where you can create discussion threads and mark them as resolved. This is very important when you need a lot of input from the customer, for instance, from their developer teams.
ClickHelp had some glitch though when I tried to change the level of headings: it messed up their IDs in the underlying HTML code. I had to open the integrated HTML editor, search for the IDs, and replace them manually. Another time it won’t add a new line after some elements, so I had to switch to the coding again.
But the HTML editing view on its own can be considered rather an advantage: I was able to add some custom HTML formatting. Besides, ClickHelp has a few fancy elements that can make your documentation article look interactive.
One of them is a popup element that allows, for instance, to hide repeating sections.
Last but not least: link synchronization feature. I always try to link relevant articles to each other in the documentation. It is not only of high SEO importance, it helps users to navigate between concepts that are related. And then, when I change an article title and its URL … You know what I mean? I have to search through the docs to replace all links!
In ClickHelp, there is a special GUI feature for it.
ClickHelp definitely has even more to offer but, as a freelance technical documentation writer, I particularly enjoyed these:
- drag-and-drop documentation structure
- comments and change history for revision and collaboration
- HTML editor + CSS customization
- link replacement feature
I would love to work with the tool again.
Docusaurus is an open-source tool that renders your documentation from Markdown files. It takes only two lines in a CLI tool to install. Then, the structure of your documentation is defined by the folder structure where you store the MD files on your hard drive. You can render the final result locally before publishing it.
Its capabilities are limited to those of the Markdown format but most of the time you do not need more!
Stoplight has a very minimalistic design and quite a slim set of features (or, at least, what my customer paid). Basically, the content was created in the Markdown format and committed to a GitHub directory using Stoplight Studio and GitHub Desktop. I guess this combination may be optional but it was what we used.
The reason was to enable a revision process that consisted of the following steps: create a Markdown document, commit it in a branch, create a pull request. Later, inside GitHub (in the browser), the reviewer could add comments to the document.
As you may guess, GitHub also saves the whole changes history.
For me, it seemed a bit weird to create a new branch for every article and a new pull request for every revision. Maybe, there is a better workaround but that was our workflow.
Consequently, I think that Stoplight comes in quite handy when you expect multiple revisions.
As in the case with ClickHelp, creating and modifying the documentation structure can be done easily by drag-and-dropping but Stoplight does not have the ClickHelp’s arrows and hierarchy level identifiers. The structure is created through folders in your workspace.
Regretfully, the access rights issue got messy at some point: it seemed that the GitHub permission rights were not quite aligned with Stoplight’s permissions for my user, and it got one of my customer’s DevOps some time to fix it.
What I liked in Stoplight is the options for storing and embedding image files. It is possible to upload them to a Stoplight folder. But, what we did, was add a link to an image file stored in Google Drive. In both cases, it allowed to have all images in one place and not spread across the documentation. When you want to replace screenshots, you go straight to one folder and do not need to search through every article.
I use Notion for notes, ideation, and project management but it is also possible to host an entire documentation in it.
What I like most about it is:
- its Markdown compatibility
- various shortcuts
- commenting features
- options for embedding links and other documents
- page synchronization
I generally like usually only keyboard while typing. Which is not possible nowadays: but I appreciate every spared mouse click! In Notion, you can import documents that you created in Markdown or export them from Notion.
Besides, when you type, you can do a lot of things with shortcuts. For instance, like in WordPress, you can press “/” and a command palette appears. When you start typing a command, your choice will shrink to the relevant ones. Moreover, in Notion, you can type in Markdown but see the results as in a preview.
Revisions are also quite comfortable with Notion: commenting, threads, and resolving comments, plus changes history are all included although differently solved in the GUI.
I really like the option for adding captions to embedded links with a preview. It is great for collecting interesting sources when you prepare a knowledge article but can also be used in the article itself.
The synchronization feature allows to copy and paste pieces of the content and keep them identical by synchronizing their changes.
As a project management tool, Notion offers options for building custom kanban task boards or tables where you can track the progress of your content plan. In the table, you can add columns with multiple choice values to quickly change the status and you can access the content of single articles by simply clicking on their titles. No need to search for an URL and then add the link to an anchor text. However, you have to create article pages inside the table and not the other way around.
Notion offers space for both creativity and planning. Highly recommend!
I only used Intercom to create a user-facing documentation. Every article includes up to six steps and a few screenshots. For this purpose, it was fine.
Documentation Writing Tools I Did Not Like
I worked with Confluence quite a few times, and it always seemed an overkill to me. Sometimes, I just do not want to have too much choice. A modest GUI helps to structure my thoughts and documentation itself.
I remember scrolling through the fancy widgets Confluence offers. Unfortunately, it was rather distracting than helpful.
Readme revision feature just sucks. We used it with the same team we end up using Stoplight instead. Comments and reviewers’ suggestions got lost and its inline comments were really inline: they mysteriously become a part of the document.
Readme uses a kind of custom formatting that keeps only selected Markdown native features that were not enough for a product other than an API.
It also does not offer more than three hierarchy levels in the sidebar and, respectively, in the documentation.
It seems that the knowledge base tool is only a byproduct of the support ticketing platform since I only found one Zendesk article about creating and editing articles.
The content can be edited visually or as a Markdown, and formatting options are limited to those we know from the latter. There is no opportunity to comment other than Markdown native inline comments. Contrary to all other tools, you cannot at-mention a person in a comment, so your co-worker never gets notified.
WordPress as a Documentation Tool?
I never used WordPress as a documentation writing and hosting tool. Although, it seems to have a special plugin for this purpose.
I can even imagine just adding a category for documentation and creating a navigation page to organize your tutorials. However, I had customers (or was approached by a few) who were disappointed with WordPress as their documentation hosting tool and wanted to migrate to another one.
Other Factors to Consider
I wrote this blog post from the freelance technical writer’s point of view. For you and your customers, the following factors may be of importance:
- permission rights (easy to set up and transparent)
- search through the articles (for users)
- visual design
- an option to get a custom domain with your brand name
With a good technical documentation tool, your users can find information faster but, remember, that documentation writing also happens quickly and can be done in a more systematic way when your author is equipped with the right tools.
Need Advice on a Proper Documentation Tool?
Or need a technical documentation writer?
Feel free to give me a call:
+49 177 490 16 59
or drop a line to discuss your needs: