You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository has been archived by the owner on Mar 16, 2022. It is now read-only.
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.
The text was updated successfully, but these errors were encountered:
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.
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 freeto subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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: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.
The text was updated successfully, but these errors were encountered: