Use sphinx + read the doc for documentation?
Most of popular opensource projects use shpinx + read the doc for documentation. It's clear (much more than redmine's wiki), and version/code related.
What about using this for Replicant?
The actual documentation is a mess (it exists and it's a good start). Maybe it could help to improve the visibility and usability of Replicant.
RE: Use sphinx + read the doc for documentation? - Added by Kurtis Hanna 8 months ago
We are looking to leave Redmine for a number of reasons, including limitations we have experienced with its wiki.
One idea we have is to move to MediaWiki. We talk about that here: https://redmine.replicant.us/projects/replicant-infrastructure/wiki/MediawikiMigration
RE: Use sphinx + read the doc for documentation? - Added by Skoll RC 8 months ago
It is also hard to have clear and structured infos with mediawiki. But at least any could export data from mediawiki.
Personally, I am in favor of OP's suggestion and recommend switching to Sphinx as well. I find working on documentation and approving changes using git much more "floss-natural" than giving permission to "trusted" authors only when using a system like mediawiki. Imho, the latter puts up a significantly higher hurdle for new docs contributors.
RE: Use sphinx + read the doc for documentation? - Added by Fil Lupin 7 months ago
I wonder if mediawiki would not be easier to use with wikidata, especially it could help include wikidata elements for hardware by using SPARQL requests.
But my hope is only based on the fact that this tool is close to the ones used by wikidata.
RE: Use sphinx + read the doc for documentation? - Added by Denis 'GNUtoo' Carikli about 2 months ago
The issue with sphinx is that it would automatically exclude people who don't know programming from contributing.
Learning programming seems hard for many people.
The idea behind Mediawiki is also to be able to mix within the same wiki contributions from people that want to program and from people that don't know how to program.
This can be done through inclusion of sub-pages, templates and so on.
It also has some advantages that you find in git too, like the ability to export the content for offline view with some tools, and it's probably doable to contribute to it with git directly with the git-mediawiki package that is available in Trisquel 8. I probably need to find a way to package that in Parabola as well at some point.Enabling non programmers to contribute has many advantages:
- Not being able to contribute to a project under a free license (for instance if you don't know how to program) is a practical freedom issue. So it's best to avoid it whenever possible.
- Excluding non programmers would mean that the current Replicant developers would have even more work to do at the beginning. With a wiki we can do the transition at the speed we want.
The mess is also due to the type of documentation we use.
Having a comprehensive documentation like the Guix manual avoid such mess but I don't see how we could use something like that for Replicant yet. Here the structure of such documentation is very well suited for Guix as everything is tightly integrated together and well separated too. As far as I know this is not really the case with Replicant.
For instance we have a lot of work in progress documentation that is written in a hurry and that is still extremely useful as-is.
So I hope that with Mediawiki we could take advantage of its features to better organize the content and maybe one day be able to produce more compressive documentation.