Documentation: Discussing the final platform for hosting the documentation

[xiaoya-yaya]

The D&I Documentation is scattered across the repository at present, I propose hosting the documentation on Read the docs after some certain enrichment of it.

Read the Docs is:

• free
• easy to get started - full instructions and guidelines
• automating building, versioning, and hosting
• neat and authentic page styles
• qualify the docs with good navigation
• designed for technical documentation, many technical readers are familiar with the page style
• already applied by Augur（from whom we can obtain advices）

I think we can have online collaborations on documentation using hackmd or something like that, and the overall organizing can be updated on Github during the early phases. Once it is settled, we can host the documentation on Read the Docs and continue updating via Github, since they can synchronize.

[germonprez]

Thanks @xiaoya-Esther -- We are also talking about GitBook that we are going to be using for our CHAOSS community handbook. This could be an option.

[xiaoya-yaya]

Hi, @germonprez thanks for your recommendation. Actually I am considering between Read the Docs, GitBook, and Github wiki. I will do some investigations about these three platforms first so we can have comparisons.

I think which platform to be used partly depends on the requirements come up along with the development, this issue is suggested by @Nebrethar so as to get the discussion started.

[xiaoya-yaya]

Hi folks! I made some comparisons	GitBook	GitHub WiKi	Read the Docs
Cost	50% discount	Free	Free
Sync with GitHub	Yes	Surely Yes	Yes
Support markdown	Yes	Yes	Yes
Authentic	Almost display as markdown page. Looks sharp and light	Pretty simple, but neat enough	Support multiple formats, classical style, but it appears ads by the side
i18n	support	not support	support
Difficulty to use	easy	easy	medium
Tools	GitBook	no other tools needed	Sphinx

The best of GitHub Wikis is its part of GitHub repositories. Though a big drawback is the sidebar can’t go through the page, which makes the navigation not so user-friendly, and it doesn’t support a multi-language version of document if this is an insistent requirement for badging.

GitBook meets almost all the requirements we can think of, and the way of using it seems easy and light. But from what I know, it is not a free tool for the open source community.

Personally I think Read the docs seems to be the best choice, if we take cost into consideration. It looks a bit old-fashioned but academic, and it is equipped with enough features that we require for now: i18n, sync with GitHub, good navigation…