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:
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.
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.
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?
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.
Notion
a. More for internal documentation / projects?
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.
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?
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.
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.
No experience with this.
See 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).
No experience with this
See 4
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.
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).
I got introduced to MakeTheDocs at Georgia Tech, and I have been very happy to use that framework has been very. Pairing it with GitHub deploy is very nice and I think it will continue to be my choice in the future.
We use Confluence both for internal and user-facing documentation. It works well enough and has lots of “pretty” content blocks that make it easy to layout various elements. But I do worry about its portability. I’d rather use something akin to makrkdown, but pleasantness of presentation would absolutely suffer. I did explore MakeTheDocs as well and do think it would be a nice solution, but it’s a bridge too far in terms of migrating/switching at this point.
As a followup, we ended up moving from Confluence to mkdocs with the material plugin. Key takeways:
It was a lot of work, mostly on moving content over.
There is a tool on GitHub to take an HTML export from Confluence and convert it to markdown with pandoc. It still requires editing to get internal links working correctly with mkdocs. It’s marginally better than copy and pasting.
Adding a Markdown linter helps find stray formatting not converted by the tool.
Formatting. We had lots of tables and pictures that assumed a larger canvas than the markdown default, which wraps the central column at around 60-80 words following web readability guidelines and responsive design.
Github Pages are a nice way to static content.
Git-based documentation (merge requests, etc.) is more involved than (click edit, submit), but with Web IDEs and a plugin that provides an edit button help.
Overall we’re happy with it for user documentation. Using it for our internal documentation process has been less productive.