The topic has come up numerous times regarding the documentation we offer for users, developers and administrators of the Mautic Open Source platform. For reference, we currently have:
Following a discussion on the Documentation Github project about the shortcomings of Gitbook, we think we should open up the conversation around what platforms we think are appropriate for consideration.
Some of the key things I think we need to keep in mind are:
Who is the end user? Can they find, use, and contribute to the docs easily?
Multilingual - while we may start with a base language, we should look to enable multilingual
Ease of access
Search optimisation - both in search engines, and having a strong, robust internal search
Open source tooling - should not rely on proprietary tooling to build/render/manage
Version control, so we can see who made changes, and roll back, incrementally
Multimedia embedding - videos often tell a better story than text!
There are lots of different options when it comes to the way we deliver documentation. For example, we could consider:
One key feature I think would be worth including on the shopping list is peer review of proposed changes. Another is the ability to strongly couple doc bugs to doc fixes. For those reasons alone I’m in favour of something based on git, but there are several other advantages too which strengthen my opinion.
Do you mean like requiring a certain number of approvals before merging @aspiers? Like we do on the main repo? That could be a workflow thing rather than being a specific function of the tool, perhaps - unless I misunderstood.
Not really, I meant more the ability to systematically propose changes and allow anyone to review them, comment, and for them to be revised if needed before merging. For example wiki workflows don’t typically allow any of that.
I’ll just copy-paste what I wrote on Slack on the docs discussion so it would be visible here as well:
Another option would be to use Grav CMS with Git Sync plugin. Here is how the editing looks like from both ends:
Here is how a documentation page built in Grav may look like:
It’s PHP, Symfony based project as Mautic is. It’s actively maintained, open source. It’s flat file CMS so the content lives only as files. No database which makes it faster, easier to maintain and the content can be stored in git. Everyone can easily run their version of the docs locally so they can see what the result will look like. The content can be edited from the Grav administration or from git as we can do it now. It uses Markdown as we do now. They already have a skeleton for for documentations which allow us have it installed and ready in minutes. Here is a list of other features:
So folks, I’ve been poking about with Grav and so far I am pretty impressed.
Easy to use, easy to update, automatic bi-directional sync with Github via a plugin. Oauth2 plugin which means we should be able to integrate with Auth0 and enable existing community members to have web-based access at a specified role level (have not tested this as yet).
It supports markdown, so with some restructuring we can bring in our existing content, and it supports multilingual but in a slightly different way to Gitbook, in that the files are all in the same directory but with a different filename e.g.
docs.en.md
docs.fr.md
docs.jp.md
There’s a theme specifically for documentation called Learn2 which is easy enough to configure, it uses sass and has a compiler.
It’s the most promising that I’ve seen so far! I’ve been working in a private repo so far but let me know if you want to take a look and have a play!