User documentation platforms and practices?

Discussion Zone
1

Hi,

We’re currently talking about how we host our user documentation. We have a separate CMS for our public-facing content, and use D2L for training material. We’re currently using Confluence for our user-facing systems documentation, but Atlassian is sunsetting most of the on-premises Confluence offerings so we’re considering our options.

So, we’re thinking about alternatives. So far, we’ve identified:

  1. Hosted Confluence
    a. This would be the easiest transition, but still fairly expensive.
    b. It’d also break our current URLs so it’s no less disruptive to our users than moving to another service.
    c. We wouldn’t need to rewrite or migrate our existing documentation.
  2. Other Wikis
    a. Many different options, both locally-administered (Docuwiki) and hosted (GitHub, MS Teams :), etc.)
    b. Wikis are structured around community editing; we have never been able to sustain an external community of editors.
    c. Theming to brand standards can be difficult; for example, mediawiki always looks like mediawiki.
  3. Static site generators
    a. Source stored in a git repository; allows CI, deployment workflows a la GitHub.
    b. Easy to host; could easily store in an S3 bucket, for example.
    c. Limited security issues; no server-side code prevents some issues.
    d. Could allow pull requests from the community via GitHub workflow.
    e. Limited dynamic content, although you can do a lot with client-side JS now.
    f. Difficult to use for non-WYSWIG editing?
  4. ReadTheDocs
    a. A hosted static site generator, based on Markdown
    b. Has a very generic look.
    c. Design originates and feels somewhat focused on software documentation.
  5. Notion
    a. More for internal documentation / projects?
  6. Github/Gitlab-native documentation
    a. Moderately awkward to link documents within the repository to each other.
    b. Difficult to style?
    c. Not particularly friendly for folks not already familiar with the GitHub experience.
    d. Integrates well into GitHub workflow & project management, etc.
  7. Wordpress, Sitecore, Drupal, other CMSes
    a. Either hosted by campus or a cloud vendor
    b. Doable, but not really well structured for documentation?
    c. Workflows for editing and publishing can be suboptimal.
    d. (Generic joke about Wordpress / Drupal security.)

Anything I’ve missed? Anyone have good or bad experiences they can share?

Thanks,

-Andy

1 Like
2

Our website is mostly plain html. It includes headers with our branded bootstrap css and javascript. I edit the pages with vi.

I do 95% of the changes to the website, so we don’t actually do the following, but the workflow for working collaboratively would be:

  • have the files in github private to the ones who develop it - put any ‘credentials’ files, if any, in the gitignore.
  • git clone or git pull to local personal computer
  • make changes, generally with vim or emacs
  • test it locally by using MAMP, which is super easy to install and use, both Windows and Mac
  • push changes

Everyone wants the community to make documentation, but I wonder how much it actually happens. (In an ideal world, you would have a technical editor make the docs.) I am doing most of our documentation and maintenance of web pages - and I would agree to using Markdown just as fast as I would agree to using Microsoft Equation editor rather than LaTeX. But if someone else were to take over, I would ask them what their preferences were to make things as painless for them as possible. Personally, I think simple php/html is really easy to work with while allowing much more control over how to display the content than any of the alternatives.

Here is our website

1 Like
3

Personal experiences:

  1. Confluence is great as long as you plan to KEEP it in confluence. We started our docs there then had to transfer them out and it was not a fun transition. But the ease in editing and the communal access makes keeping them up to date something that everyone can contribute to.
  2. No experience with this.
  3. See 4
  4. I really like markdown based, git hosted options like these. As long as you have expertise to set it up and keep it going, the docs themselves are relatively easy to edit and the built in issue tracking makes it easy to keep a CI/CD approach to documentation and encourage participation from a wide range of people (uptake on that is a different story).
  5. No experience with this
  6. See 4
  7. This is my LEAST favorite way to do things. I have the most experience with Drupal. But trying to deal with HTML/PHP with the CMS layered in there is a huge pain. And often you are fine tweaking your HTML to combat formatting issues.
1 Like
4

We use Mediawiki. For my money, Mediawiki is the best. You can create categories ad hoc: just add “[[Category:Getting Started]]” and you now have a collection of pages for newbies. You are not limited to a traditional documentation format, which has various chapters and sections in some sort of linear order. Editing, creating interlinks between articles, uploading media (PDFs, images, etc) is easy, authentication for editors is easy (if you already have an LDAP server for your users), stylesheets/skins available for both desktop and mobile, good search built in (with ability to use Sphinx search).

Downsides: you have to manage a web server and a database server, keep up with security patches (this is a PHP application after all).

Re branding: a bit complex to do, but there are many existing skins that one could do an OK job (colors, icon, and logo image are pretty easy). As a bonus, you can try them out live on Wikipedia (if the skin is available there).

1 Like