Documentation Platform/s

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:

  • Documentation-specific applications such as Mediawiki (I did a bit of poking about a while back see: https://www.youtube.com/watch?v=7643XZjXPIw, sorry for the sore throat and coughing!)
  • Git-based documentation tools which render to a web-friendly format (with a better user experience than Gitbook!)
  • Content-based approach, similar to a knowledgebase within a website like mautic.com/help, for example

What are your thoughts?

Do you have any suggestions for tools we might consider using, or features/functionality we might need?

1 Like

@aspiers @virgilwashere here’s the discussion thread about documentation platforms

1 Like

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.

1 Like

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:

Wow, that’s really neat!

I presume it’s possible to set up roles in the Grav site to give people access to the content?

I really like that is easy for people to either edit on the web or use a code interface!

We’d have to test that. There are users and groups in Grav:

There are also some plugins that make it easier to manage users and groups like this one:

But I don’t have personal experience with it. I use Grave only for personal projects.

1 Like

Also supports multilingual as well: https://learn.getgrav.org/16/content/multi-language

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!