Multilingual docs / docs evolution

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.

  1. Add multilingual capabilities to the existing setup with Jekyll and Github Pages

    Pros:

    • Requires little to no change to build system
    • No use of external code = full understanding of system (for who ever sets it up)

    Cons:

    • Significant changes needed to docs structure
    • Potentially limited return for time spent
    • Limited existing resources on suggested implementation (I did find one brief tutorial)
  2. Use Jekyll plugin (e.g. this or this)

    Pros:

    • Less time required than option 1 (hopefully)
    • Existing users, tested etc

    Cons:

    • 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
  3. Transition to different docs system (probably not the right word!) such as Docusaurus

    Pros:

    • 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

    Cons:

    • 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.

Other considerations:
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)!

If the goal is to increase the opportunity for more users to learn and enjoy Parse and ultimately drive more deployments of Parse into production … than I’m all for evolving the documentation.

The fact that Docusaurus is well maintained and has multi language support baked does suggest the tool is the leading contender.

I’d love to help but being an ignorant English speaker maybe there is not much I can do. I’ve been spending a lot of time recently in the documentation so maybe there are some edits/additions that I can provide.

Thanks for your thoughts. I also only speak English but I hope by setting up the translation systems others will help by providing translations.

Generally speaking, I would be more than happy to accept any edits to the docs - send in as many PRs as you want, I keep a close eye on the docs so PRs are generally quickly reviewed and merged!

As a starting point you can take a look at the issues labeled ‘missing content’ for features that need documenting.