How to contribute

You’d like to contribute to this documentation? First of all: thank you!

  • You found a typo that you would like to fix? …

  • You think that an explanation is bad, and would like to clarify it? …

  • You noticed a gap in the documentation that you would like to fill? …

  • You detected an obsolete information that you would like to update? …

  • You want to translate this documentation into another language? …

… Your help is welcome!

This project uses a ticket system to discuss the objectives and to track the remaining or already completed tasks. Therefore, please feel free to use these tickets. You can thus contribute to an existing discussion. You can also submit a request or better yet, offer your help.
The ticket manager can be found at
https://gitlab.huma-num.fr/datasphere/doc/en/issues/

How this stuff works

Each page of this documentation is initially written in a plain text file. The syntax used is reStructuredText [1] [2]. This is a fairly simple syntax, suitable for representing complex elements in a simple text file. As an example, you can click on the “View page source” link that may be found at the top right of each page on the website: this will allow you to see how that page is written in reStructuredText.

Each time one of these files is modified, the Sphinx Documentation Generator [3] produces various output formats, among them a book in PDF or EPUB formats, as well as a website that makes it easier to find any information.

The generated website is in turn hosted on Read the Docs [4], a well-known documentation hosting service.

All this is flexible, based on free software, and perfectly reproducible.

Note

Why not use Markdown?

The principle of reStructuredText is similar to Markdown/CommonMark [5]. However, by default, the latter does not support some elements such as tables, inserts or footnotes. In addition, Markdown is not suitable for automatic generation of tables of contents or indexes. Finally, one of the aims of this document is resilience. However, Markdown suffers from glaring flaws at the conceptual level [6] [7], which seem to be a hindrance to this issue.

Note

Why not use pandoc? [8]

I have nothing against pandoc. At some point choices must be made, that’s all. You can also generate this documentation with pandoc, if you like. And if you do so, would you mind sharing it with the community ?

Note

Can Read the Docs be trusted? [4]

Read the Docs Community pricing offer is “always free” for open source projects like Datasphere. Of course, a promise is only as good as the one who makes it. However, this offer has been running since 2010, which is certainly to their credit.

But what if Read the Docs suspends its offer?
As explained above, the build system of this documentation is entirely reproducible. It could therefore easily be hosted elsewhere, for example in a research repository. It’s also possible to host it nowhere in particular, since anyone can freely rebuild it.
Anyways, this will not make this documentation unavailable, since a mirror site already exists here: https://datasphere.gitpages.huma-num.fr/doc/en/
And what if Read the Docs “steals” or “leaks” data?
Datasphere is free software, and its documentation is no exception. It’s a free gift, with no time limit, to anyone who wishes to use it. If that gives you a thrill, you can just imagine you’re “stealing” it. Now you’re such a meanie, heh? (づ｡◕‿‿◕｡)づ

References