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:
- End-user Documentation (powered by Gitbook, via Git)
- Developers Documentation (powered by Slate, via Git)
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?