From HTML Help to Markdown websites

I have been writing and building online documentation (online help) since I started, and in HTML since 2000. It is one of my specialties.

Although Help can still be created by writing HTML in a text editor (like I really did for my first HTML Help!), nobody does. The content of the Help should be attractive and responsive, that’s why after using a lot of HATs (Help Authoring Tools) I now use a static site generator / Markdown files combination.

🔸 Structure Fundamentals

From pure HTML of early Help websites to static website generators, the fundamentals remain the same.

First, the structure that is still a tri-pane one, inherited from the time when the frames dominated:

  1. On the left, the TOC (table of content) with up to 2 sub-levels. Now named “the sidebar”.
  2. On the top, the menu to switch to another language or display shortcuts. Still available in the the most current documentation websites.
  3. The main frame, to display the content. Often starting by a sub-menu to have a view on the page content and ending by various “See also” or “Previous/Next” links. Now the sub-menu is out of the page, but still available on the upper right corner.

An essential contribution of RoboHelp to online documentation was to build Help websites, either packaged and compiled to get a single .chm file or as “webhelp” with the index.html start file, both with a search engine, a expand/collapse menu and an index.

🔸 They Disappeared (or if only They Could)

The index inherited from the era of printed documentation, is unfortunately the victim of modern documentations: this feature is no longer available in static site generators, but who would still have time to develop one manually? Do you, technical writer, remenber this fastidious work to track every term through so much pages?

Other victim, the pop-up link formatted with green dashes used to display a definition or explain an acronym inside the paragraph. I liked this type of link.

Misuse that I would like to see disappear: the large tables containing everything and anything, just because it saves sentences and because it was used at one time to format content in HTML pages (worst of all, the table in the table). Luckily, Markdown does not allow this 😃

🔸 Content Fundamentals

Regarding the content, a good Help is action-oriented, structured, with quite short pages. It is maintainable (updates, multi-languages) and provides a smooth navigation (built automatically in many static site generators). It contains basic topics such as a glossary. These fundamentals were already relevant 20 years ago.

⭐ The sites below are inspiring me, that’s why they are in my favorites!

  1. 🔗 Docusaurus v2
  2. 🔗 Hugo
  3. 🔗 Jekyll

This website for example is a combination of Markdown files, Yaml files and a cool Hugo template. Other examples are available in my 🔗 Portfolio.

I used RoboHelp a lot, which allowed online help in HTML with search engine and index as early as 1999. 🔗 Adobe RoboHelp is still a complete solution that allows you to customize your design, manage content and generate searchable immersive help regardless of device or format. However, RoboHelp creates files in HTML and does not use Markdown.

Read this other post about 🔗 Markdown.