Skip to content
This repository has been archived by the owner on Mar 16, 2022. It is now read-only.

Documentation: Discussing the final platform for hosting the documentation #29

Open
xiaoya-yaya opened this issue Jun 23, 2020 · 3 comments

Comments

@xiaoya-yaya
Copy link
Member

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
Copy link

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
Copy link
Member Author

xiaoya-yaya commented Jun 24, 2020

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
Copy link
Member Author

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…

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants