Description
We aim to replace the current developer documentation at https://developer.mautic.org/ with a new one on Read the Docs. These docs are to be put at https://mautic-developer.readthedocs.io.
Background
- Large parts of the documentation were written in the Mautic 2 era, resulting in many external links and code examples being out of date
- While we have automated deployments in place, we have to maintain the server at https://developer.mautic.org ourselves (OS/security updates, etc.). This adds a maintenance burden to the infrastructure team
- The current documentation is basically one immense page, leading to a long initial load time and non-ideal user experience
- Mautic supports multiple major versions at the same time. When Mautic 4 is released, Mautic 3 will still be supported through bug fixes for a while. The current platform, Slate, doesn't have built-in support for multiple versions of documentation. Read the Docs, however, supports this out of the box.
- Some developers feel lost when they start working on or with Mautic. It'd be ideal if we could take developers a bit more by the hand. We can do so by providing them with a working development environment without too much effort. Recently, Mautic has added a built-in DDEV configuration, which allows developers to simply run
ddev startand have DDEV set up everything for them automatically (PHP, database, MailHog, Mautic installation, etc.)
The goal
By moving to Read the Docs, we hope to solve the pain points above and provide developers with a smooth experience when they work on or with Mautic.
The strategy
In order to reach our goal, we need to split up the work into various chunks. If you would like to write a certain section - or a part of it - please leave a comment in this issue, so that we know who's working on what. Your help is greatly appreciated!
Sections that need to be moved over:
- Plugins
- Marketplace (as part of the Plugins section)
- Cache Bundle (as part of the Plugins section)
- Themes
- Webhooks
- MauticJS API
- REST API (to be discussed later*)
* = Ideally, we'd like to have auto-generated REST API docs, so that they're always up to date. An attempt was made to make that happen, but at the moment of writing this doesn't seem worth the effort as Mautic next-gen will have auto-generated REST API docs right from the start.