I’ve been looking into the possibility of making the docs multilingual in an effort to make the Parse Platform easier to use for existing users and encourage new users by an inclusive approach to documentation.
I’ve considered three options to achieve this. It’s worth noting that for all three I suggest using a service like Crowdin to manage the process of making translations (it integrates nicely with GitHub). I’ve obtained a free open source license that can be used by the Parse Community for this purpose.
Add multilingual capabilities to the existing setup with Jekyll and Github Pages
- Requires little to no change to build system
- No use of external code = full understanding of system (for who ever sets it up)
- Significant changes needed to docs structure
- Potentially limited return for time spent
- Limited existing resources on suggested implementation (I did find one brief tutorial)
- Less time required than option 1 (hopefully)
- Existing users, tested etc
- Can’t build site with GH Pages - have to use CI to build site and push to GH Pages (fairly simple)
- Not very actively maintained
- Still requires significant changes to docs structure
Transition to different docs system (probably not the right word!) such as Docusaurus
- Well maintained - used by lots of top open source projects, financial backing on open collective
- Existing multi language support - with support for Crowdin
- Other features gained - document versioning, copy code buttons (yay!)
- Likely to be less layout bugs etc
- Requires significant changes to structure & build system
You can probably see that option 3 is my favoured option. Although it would require significant effort, I think the positive return would better than the other two options. @flovilmart did start a Docusaurus branch so that could form a starting point, although I have no idea how far he got or how out of date it is.
There is a topic discussing the possibility of consolidating the docs which is something I also explored. I looked at using Slate to do this which works very well but doesn’t have built in multilingual support, copy code buttons and isn’t doesn’t have very active contribution. Moreover there has yet to be significant interest in this (in my opinion) and I think it would likely be more of an effort than transitioning to Docusaurus. Nonetheless, I appreciate the value of this style of docs so I’m not disregarding it I just want to open a discussion about translating the docs and where it’s long term future lies.
I’d like to hear the thoughts of other maintainers and the wider community before going much further with this, so please chime in (positive or negative)!