Skip to main content

Online Doc Fundamentals

· 4 min read
CoffeeCup
CoffeeCup
Senior Technical Writer

The Help Files Evolution: From Pop-Ups and Frames to Markdown Bliss​

I’ve been building online help since the early days — back when HTML ruled and editors were mainly plain text. Things have changed a lot, but some fundamentals are still going strong.
In this piece, I look back at how Help has evolved, from RoboHelp and tri-pane structures to the cleaner world of Markdown and static site generators. It’s part nostalgia, part practicality — and all about making documentation better.

🟢 I’ve been writing and building online documentation (online Help) since I started, and I’ve been working in HTML since 2000. It’s one of my specialties.

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

Online Doc Fundamentals

Structure Fundamentals​

From the pure HTML of early Help websites to today’s static site generators, the fundamentals remain the same.

First, the structure is still a tri-pane layout inherited from the era when frames dominated:

  1. On the left, the TOC (Table of Contents), with up to two sub-levels. Now called “the sidebar.”
  2. On the top, the menu for switching languages or accessing shortcuts — still used in most documentation websites.
  3. The main frame displays the content, usually beginning with a sub-menu offering a page overview and ending with "See also" or "Previous/Next" links. These sub-menus now appear outside the page, often in the upper right corner.

RoboHelp made a significant contribution to online documentation by generating Help websites that were either packaged into a single .chm file or published as “WebHelp” with an index.html start page. Both formats included a search engine, expandable/collapsible menus, and an index.

They Disappeared...​

or for some, if only they could

The Index​

The index, inherited from the days of printed documentation, has sadly vanished from modern Help sites. Static site generators don’t support it natively, and who has time to build one manually? Do you, technical writer, remember the painstaking task of tracking every term across countless pages?

Another lost feature: the pop-up link formatted with green dashes, used to display definitions or explain acronyms inline. I used to love those.

While it's theoretically possible to recreate this behavior in Markdown using HTML, this isn't supported natively in Docusaurus. Other static site generators like Hugo or Jekyll may support tooltips via plugins or raw HTML, depending on the theme and configuration.

Large Tables​

One misuse I’d like to see disappear entirely: large tables packed with everything imaginable. These were used to save on sentences or format layout — often resulting in nested tables. Thankfully, Markdown doesn’t allow that. 😅

Content Fundamentals​

Good Help content is action-oriented, well-structured, and built on short, readable pages. It’s maintainable (for updates and multilingual support) and offers smooth navigation — something many static site generators handle automatically. It also includes basic features like a glossary.

These fundamentals were already relevant 25 years ago.

Favorite Tools​

The sites below inspire me — that’s why they’re in my favorites!

  1. Docusaurus v2
  2. Hugo
  3. Jekyll

My previous website (2019–2024), for example, was made using a Hugo template, combining Markdown and YAML files.

I used RoboHelp extensively, which allowed online Help in HTML with a search engine and index as early as 1999.

Adobe RoboHelp is still a powerful solution for customizing designs, managing content, and creating immersive, searchable Help for any device or format.