Integrating a documentation/help engine with Omnis desktop app
cilkay at gmail.com
Tue Nov 22 23:26:10 UTC 2022
I fall into the "docs should be HTML" camp. As Doug wrote, WordPress and
Drupal could be options. WordPress and Drupal are easy to set up but
require some ongoing work to keep patched. Both can work "headless" so that
you can materialize the pages as static HTML. Hosting static HTML is easy
and cheap not to mention, you don't have the usual issues you would with a
database-backed CMS which requires vigilance to make sure that a security
hole doesn't end up with your site defaced or held for ransom. You could
host WordPress or Drupal internally and have a CI/CD pipeline to deploy the
materialized pages to something like Netlify, Github Pages, or Amazon S3.
S3 buckets are durable, cheap, scalable, and fast so they're perfect for
throwing a bunch of static HTML files into and make them available to the
Doug mentioned Markdown. There are Markdown editors that hide the
complexity of Markdown, which looks simple to tech folks but inscrutable
for non-tech folks. I've wanted to replace a wiki that a former employer
still continues to use long after it should have been upgraded with a
static site generator that can automate the publishing of documentation but
the sticking point has always been the need for people to understand
revision control. Many developers have difficulty understanding revision
control so to expect non-tech people to understand it is a bridge too far.
The advantage of a headless WordPress or Drupal setup is that it eliminates
the need for users to know a thing about revision control.
Wikis are the natural choice for collaborative user-generated
documentation. Have a look at https://medevel.com/os-wiki-engines-for-2021/
to see if there is a wiki you like there. We used to use XWiki at Amazon
until a few years ago. We built our own wiki engine internally that
integrates well with all the other tooling we've built for software
development so we no longer use XWiki but there are still many pages that
are hosted on the new wiki that are still in the legacy XWiki syntax.
More information about the omnisdev-en