Starting a new topic on maintenance and planning around the SC Wiki. 
The wiki has lots of outdated info, crusty pages, and could be more useful.
Having started a bit on the task, I see it’s a bit ambitious to aim for a complete overhaul. I don’t want the perfect to the enemy of the useful, so I’d like to make incremental changes that start with reorganizing, building in a bit of structure, and consolidating some of the more high-traffic pages.
UPDATE: The following proposal is outdated. See my post below for the new proposed structure and a working model with some newly edited wiki pages.
As a first step, I’ve mocked up a new, slimmer home page and sidebar on my SC fork.
(Note many links are just placeholders.)
The goal with it is to make all wikis visible from the sidebar, but using a nested structure to have the most useful visible (no more than 3 per level-1 heading), with the rest in categorical dropdowns.
This way, we can hopefully 1) discover what’s there more easily, and 2) see we have a lot of redundancy or dust to clean up.
How to move forward?
I’d like to hear feedback on this proposed structure (knowing it can/will evolve), and hear of other ideas people would like to see in a revised wiki.
Is this something that should be an RFC?
Or can we organically discuss here and make incremental changes?
For example, here are a few ideas on improvements, to give an idea of the kind of discussion it may/not evoke:
-
(already mocked up) Create a new sidebar with a nested structure 2 levels deep. Pluses: All pages can be found, 2 levels of categories for navigation. Downside: nested structure require html (though the template is now made and will change infrequently)
-
Add tables of contents to all wikis that have more than 3 header tags or extend beyond ~3 page heights.
-
Move all “WIP” wikis out of that state — we accept that wikis are by nature works in progress, and WIP wikis tend to stall because of the label.
-
Add a wiki about the wiki, which includes style suggestions.
There’s likely another 5 or 10 similar suggestions… Should I float them all before implementing them, or, given it’s a wiki, should I roll them out them point back to them to draw attention for feedback?
1 Like
Thanks for taking the initiative here! totally agree the wiki needs love…
my inital reaction is yes so much better to see “Contributing to SC” the first item in the sidebar instead of a guide to fedora!!!
I’d say roll out your ideas and let the rest of us complain afterwards. I’m excited to jump in and do clean-up and proofing where I can
…but sadly the wiki can only be edited by folks with project write privileges 
Right there on the first page is an invitation to
which have been closed for 3 years. …grrrr
Thanks for your thoughts @semiquaver! It was your questions at the last sclang meeting that brought me back around to the wiki, remembering at some point I’d started to write up a wiki on some of the dev processes people often ask about 
I’ll let this discussion go for a week or so before making any big changes.
I don’t have permission to edit the access control list, @josh ? @MarcinP ? Could we give @semiquaver permission for editing the wiki?
@semiquaver — I did a quick search and couldn’t find ‘semiquaver’ on github, do you have a different handle there?
Thanks Mike I’m cdbzb on GitHub…
I’ve circled back around to the revision of the SC wiki and I now have a mirrored example of the new proposed wiki structure with updated content.
There are two points to consider for feedback:
1. The structural revision
I had originally planned to simply reorganize the structure of the sidebar, and add some formatting to make it less monolithic. But this meant having to use HTML to nest pages in categorical dropdowns, the benefits of which didn’t outweigh the maintenance cost.
Instead, I introduced the concept of Directory wikis, which would be much easier to maintain, and greatly cleans up the sidebar. This means that all pages in the wiki system two clicks away, instead of one. There are currently four Directories: Contributing, Development Resources, User Resources, Community.
2. Page revisions
I revised and/or added about 15 pages—those that I thought needed attention for development efforts or that impacted the wiki’s structure. Some are ground-up rewrites, some just update some language, links, formatting etc. You’ll be able to see which pages have been rewritten because the links will be blue in the Directories. Red links are dead ends that are stand-ins for all the other pages currently on the public wiki, which I don’t intend to touch. But it gives you a feel for the new structure and the current scope of content.
Here's a list of pages I added / touched / renamed
- Home- Reviewer instructions
- Labels and milestones for PRs and Issues
- Releasing cycle and process
- Style guidelines: SuperCollider
- Style guidelines: Cpp
- Style guidelines: SCDocs
- The wiki wiki
- Ways to contribute to SuperCollider
- Reporting bugs, issues, feature requests
- Creating pull requests
- Rebasing a PR
- Community Channels
- (+ Directory pages and sidebar)
If there’s agreement that this is a worthwhile update, I can migrate the content. My hope is that this new structure is more conducive to actively updating content, making it easier for new information to find a home within the existing structure, and reorganizing what’s already there—I see my proposed changes as preliminary to the work that should be done on cleaning up the wiki.
I’m open to any an all feedback, but in particular wrt the structural changes or the scope of particular categories or pages. I did spend a good bit of effort on copy editing and formatting those pages I revised to hopefully set the stage for consistent formatting going forward. But feel free to revise and reorganize if you see opportunities for improvement… it’s a wiki after all 
I also made a new wiki documenting this new structure, and some guidance on formatting and adding content. It would be great to have feedback on this, since it amounts to an informal “style guide” for the wiki, which is best arrived at collectively.
2 Likes
this is fantastic - a huge improvement. I haven’t looked through all the pages yet but it feels much more manageable off the bat.
1 Like
At the last developer meeting it was decided to go ahead with this update to the wiki layout. I’ll try to get to this in the coming days, but this space is still open for feedback and discussion in case others have thoughts ahead of the change.
3 Likes
Most of the restructuring has now taken place: Home · supercollider/supercollider Wiki · GitHub
One issue came up: it appears changing a wiki’s name obscures the wiki’s revision history by showing only 1 revision once the page is renamed. Changing the name back to it’s previous name then shows the full revision history. hmmm… GitHub bug? So I’ve noted the previous name in the commit message renamed pages that have any substantial history.
Hopefully the new structure makes it more navigable and also more obvious where there are content gaps or a need for revision and refactoring. So everyone feel free to tidy the wiki up now 
Please also keep an eye out for external links out in the wild pointing to renamed wiki pages that may need to be updated. I had to rename some pages that had extra spaces, or to make them consistent with similarly themes pages (like FAQs). Pages renamed to conform to the sentence case style recommendation should still be ok.
Also renaming the topic to be more generally about anything related to the wiki.
2 Likes
Those interested in an alternative host, new layout, and editing process for the wiki may want to discuss this issue:
@dscheiba, who mocked up the proposed wiki, lists some of the advantages:
- independence of any hosting platform - hosting a static website can be easily done these days
- searching the wiki
- editing can be performed offline
- internal references can be checked for dead links at build time
- custom styling
- Clear PR workflow (how can the current wiki be edited? It has a git repo but how do I make a PR on it?)
- website structure is independent of folder structure, which allows to improve the organization of files
1 Like
How does one go about contributing to the new wiki? Frankly, I often forget it exists.
I’ve just visited a few pages, encountered broken links, and stumbled upon certain statements that seem ripe for discussion.
SuperCollider is licensed under the GNU GPL, a fairly restrictive open source license.
Take, for instance, the characterization of the GPL license as “restrictive,” which strikes me as inappropriate given its fundamental emphasis on freedom. I find it somewhat overstated to attribute specific issues solely to the GPL license. It often has nothing to do with it. This particular sentence really got my attention.
In principle, a well maintained wiki could be a very important document for the project, as long as people visit and edit it.
As I understand, you need to be a member of the SC GitHub Organization to edit the wiki. To be added to the list of members, I believe you’d have to just contact someone with Owner status to add you.
Then you could update that statement about the GPL with more neutral language
That is the hope!
If you have thoughts on the proposed wiki migration pls see that PR linked above. We’ll need more eyes on it for it to get traction.
1 Like
wrt access control in the newly-proposed wiki: does a PR process from individual user forks offer more open access?
How much overhead is anticipated for reviewing and merging wiki edits? Should “trusted members” be able to merge their own PRs?
I’d propose to give some familiar people direct commit/write access on the main branch, which would mean that those people wouldn’t even need to do a PR to perform changes - maybe only on bigger issues or where feedback by other people is wanted I’d propose to still perform a PR.
People w/o this direct write access would need to go through the traditional PR workflow - in the status quo there is no way to propose a change w/o having write access to the wiki, so the range of participants could also be widened by this proposition.
btw - to those who have not visited the issue, the new proposed wiki can be accessed here https://capital-g.github.io/supercollider-wiki/index.html
1 Like
I’m not clear what you mean by this, could you elaborate?
And to be clear, this discussion of the PR process would apply to the newly proposed wiki @dscheiba linked to above
The current wiki is a bit stale and falls off the radar for being out of date and hard to navigate. The goal of these stepwise improvements is to make it more alive and useful, I agree. The information that lands there will be fairly static, but that’s ok for reference information, as long as it’s accurate and up-to-date.
In lieu of an alternative at the moment, I think the PR process does bring the advantage of having more eyes on updates there, so there’s a bit more of a team effort to make sure it’s organized, accurate, and complete.
This forum is good for being “alive” and has lots of useful and timely information, but despite there being “topics”, it’s fast moving with a lot of OT chatter and sprawl that make finding otherwise info difficult.
1 Like
Meta-comment, it is so hard to follow what is going on here because there are conversations happening on both Github and Discourse, and lots of off topic digressions about unrelated issues. The RFC process is the usual route for making large proposals such as this, I suggest to use that out of respect for everyone’s time.
This Topic is about anything related to the SC Wiki. The specific issue of the proposal for hosting the wiki in a new format has an open PR, linked above. Whether that should be a Discussion RFC instead could be suggested there.
I agree, btw, that an RFC would have been a good way to frame that proposal.