search

supercollider / supercollider.github.io

Website for SuperCollider
http://supercollider.github.io
32 stars 79 forks source link

Move wiki pages to GH wiki #247

Closed gusano closed 3 years ago

gusano commented 3 years ago

Hi everybody, it's been a while :)

What about moving all wiki pages from the website to the Github wiki? I have some free time...

Website WIKI pages

dyfer commented 3 years ago

I'd be generally in favor of that! One thing to consider is that our GH wiki is generally more contributor-oriented, while the website wiki has a mix of user- and. contributor-oriented content. What I'm saying is that some restructuring might be needed to maintain reasonable order...

I feel like most of the contributing/PR/dev content on https://github.com/supercollider/supercollider/wiki could be moved to a separate page, and then that page could inherit some of the links from the website wiki (and of course all pages should be added to the navigation on the right).

IMO you can start making the changes and we refine them as we go. Thanks!

dyfer commented 3 years ago

Also note some tips on editing the wiki in the other thread (not sure if that's best, just pointing it out as an option)

gusano commented 3 years ago

@dyfer I agree. I'll add a list here of things to do and proposal of changes. It will be a slow process so I'll have a go and we'll refine it. Thanks

gusano commented 3 years ago

@dyfer I think most of the contributing section is either deprecated or too much information. I'm gonna move it to SC WIKI but I have the feeling that we'll end up with too much content on the WIKI and that no one is gonna read it :smile:

I updated this issue description with the list of all pages and their status.. This is of course open to discussion but I'm gonna start copying things already anyway.

dyfer commented 3 years ago

I'm gonna move it to SC WIKI but I have the feeling that we'll end up with too much content on the WIKI and that no one is gonna read it 😄

Yeah, it would be great to not move outdated information :) If you can skim through it and can condense it that would be great. But if not, I'd clearly mark it (on the new wiki, on a separate page) as "outdated information" with the idea that someone at some point will get to cleaning it up...

Thank you for working on this!

gusano commented 3 years ago

@dyfer What do you think about the two Error pages (misplaced in the tutorials section)? https://supercollider.github.io/tutorials/error-primitive-basicnew-failed https://supercollider.github.io/tutorials/server-failed-to-start

It's been a while I've been out of the loop with sc development, are they still needed or even used?

dyfer commented 3 years ago

https://supercollider.github.io/tutorials/error-primitive-basicnew-failed

I think this is still relevant, but shouldn't live on the wiki - it would be good to migrate this to the help system. Not sure where's the best place - it would be great if the user could search for it... at the very least, it could be added to the SynthDef helpfile.

I feel like the user faq should also belong in the help... but maybe not? what do you think?

https://supercollider.github.io/tutorials/server-failed-to-start

This is outdated and can be removed, since the error message is more verbose now and does suggest what to do (killing all servers).

gusano commented 3 years ago

I feel like the user faq should also belong in the help... but maybe not? what do you think?

I agree that some of it could go in the Help but that page contains several sections:

gusano commented 3 years ago

@dyfer ping :)

dyfer commented 3 years ago

Thanks for the ping @gusano , I've missed the previous message. Now thinking about this, since this page was designed as a "catch-all" faq (I think?), how about moving the whole page to Tutorials as is (with a note that this was transferred from the wiki)? Then it could even be linked from the Help's home screen "Getting started" section. Additionally, I think it would be good to link it to (and link to it from) all applicable pages: Server helpfile, SynthDef helpfile, Guides -> GUI... Also, as you make the transfer, it would be great to update the error message for the GUI example to the current one:

ERROR: Qt: You can not use this Qt functionality in the current thread. Try scheduling on AppClock instead.
ERROR: Primitive '_QWindow_AvailableGeometry' failed.

EDIT: I also think that as you make a PR for the documentation, other devs might pitch in with an idea how to organize it better

gusano commented 3 years ago

@dyfer I'm gonna move the content of the Error... file and User FAQ into an Errors FAQ page and add the links to the doc

gusano commented 3 years ago

@dyfer I did what you suggested and created a PR with links to the Errors FAQ page.

Now I have more questions :)

dyfer commented 3 years ago
  • what about adding examples / code examples to the examples in the source code? There's only one code snippet from James Mc Cartney

Maybe that could be added to regular help (with attribution) to examples section for one of the filters used (RHPF/LPF/OnePole)

  • are development / plugins and development / scsynth still up-to-date with current code base?

IMO both could be moved as they are to pages in the "developer" section of the new wiki. Plugins doc is accurate AFAIU (though I'm not sure if that PDF link works). As for scsynth page - I don't know how accurate it is, but I believe most things still apply. I'd move it as is for now.

gusano commented 3 years ago

@dyfer While porting User FAQ to SCDoc I ran into an issue. I can't find how to link to the document anchors/subsections:

subsection:: SynthDef Issues is rendered by SCDOC as <a class="anchor" name="SynthDef Issues">...</a>

An HTML link like ...#SynthDef%20Issues works, but when using link::#SynthDef%20Issues in the schelp file, %20 is escaped and the link ends up with spaces instead, which does not work :|

I'm not sure how to fix that... That means no links to the subsections right now, which, with the content of that file being a mix of everything, is a bit messy.

If you have any idea...

EDIT: nevermind, I read the doc and found anchor:: :see_no_evil:

dyfer commented 3 years ago

IIRC the anchors might have spaces removed, would link::#SynthDefIssues:: work? Actually, an example in help shows anchors with spaces, how about link::#SynthDef Issues::?

gusano commented 3 years ago

@dyfer OK I'm almost done :) I have the feeling that the 2 last pages (the infamous contributing ones :japanese_goblin: ) are not really needed as the current WIKI has already a lot of information on how to contribute, and that too much information doesn't help. I'd bet that probably very few people has read them anyway so I'd be in favor of not copying them, what do you think?

dyfer commented 3 years ago

thanks so much @gusano !

I agree that the current wiki probably has most of the information. However, if you could skim through the old doc and look at the current instructions to see if there are any specific points worth copying, that would be great.

gusano commented 3 years ago

@dyfer I already checked and I don't think there's anything worth copying except the paragraph about labels. I'm gonna add a Issue Labels page in the WIKI resources and close this issue ;)

gusano commented 3 years ago

Closing this one, feel free to re-open if you feel that something has been forgotten

dyfer commented 3 years ago

Note to self: after https://github.com/supercollider/supercollider/pull/5507 is merged let's replace the website's wiki with a single page linking to SC wiki and this repo's wiki, OR just link straight to the SC wiki