Recently the state of the Wiki came up again due to an outdated post and there has been an RFC idling around for some time about the wiki, so I thought it would be best to ask here for some opinions on how we could improve the status of the wiki.
The question “why even a wiki and not SCDoc/within the SC repository” is simply explained by the scope of the Wiki: It covers everything needed to get SuperCollider up and running, provides resources for developer (it is a good resource for people who want to start contributing), a collection of learning resources and it is also a storage for agreements and formalities around development and releasing SuperCollider.
Anything related to the use of SuperCollider should not be part of the wiki, but should be put into SCDoc.
With that out of the way, let us look at some possibilities with some personal annotated pro/cons
| Way | Pro | Con |
|---|---|---|
| Status quo / Keep Wiki @ GitHub, see here | - Existing References keep working - No additional work necessary |
- References/Links are tied to GitHub, which creates a lot of friction if we ever have to leave GitHub. There are currently no plans to leave GitHub, but I think it is better to avoid any ties/lock-ins, especially those that affect a community such as a URL for a Wiki, see e.g. the old sourceforge wiki - No automatic TOC creation and no search functionality -Requires GitHub account |
| Switch to an independent static site builder, see here | - Documentation can also be bundled and used offline - Automatic TOC creation, search functionality and automatic broken link detection - Can be hosted at an URL independent of GitHub - Changes can be reviewed in a Pull Requeset manner - Changes can be worked on and preview locally - Control over styling and structure - As a static website it can be hosted really easily and without much maintenance and resources |
- Changes must be commited via git - Requires a local setup and knowledge in git as a barrier |
| Use (this) Discourse as Wiki | - A wider userbase with a low entry barrier for contribution due to familiar editor and interface - No git knowledge or local setup necessary - Allows commenting on a Wiki article, e.g. if it becomes out of date or questions comes up which can also be helpful for other users - Search functionality |
- Sharing the same space for forum and wiki may lead to cluttering - Discourse URLs are not the nicest |
Please note that discourse has a wiki post feature, see here, which allows that a post can be edited by anyone with the proper rights.
The discourse community (as well as some others) are also using their discourse instance as their wiki, see e.g. Community wiki - Discourse Meta .
This would also not necessarily lead to clutter in the latest feed, as it is possible to exclude categories from being displayed in the latest feed, although it might also be interesting to inform users about (upcoming) changes this way.
I personally favor the discourse way as I’d like to keep encourage people from scsynth to contribute to the SuperCollider development. When talking with people about contributing to SC they often seem to feel intimidated by all the necessary conventions and setup to contribute within GitHub, which I can understand.
Also, I think the way to comment on a wiki post is really beneficial because in the status quo there is now way of indicating “I think this is out of date” or ask some questions.
Please discuss and feel encouraged to state your opinion on it so a decision, even if it is keeping the status quo, is backed by the community.