Ideas & code examples, aimed towards new users for building a simple workflow & editing, updating, writing & rewriting documentation… all the way up to submitting a basic pull request.
Everything including the syntax reference is all there.
Beyond this, it is critical from anyone with any level of experience to allow us some form of wisdom regarding practical usage of these classes, along with the process for writing documentation in general.
I know @elifieldsteel contributes to the docs, and is also the current champion of recommended tutorials for SC on YouTube… if we’re lucky, he’ll throw in a few words regarding his own modus operandi.
My contributions to SC are generally quite small, mostly documentation adjustments e.g. spelling/grammar corrections, minor clarifications via rewrites, standardizing capitalization choices, etc. As some may already know, I created a tutorial in collaboration with @VIRTUALDOG which provides a walkthrough of the essential steps and, I think, is reasonably well described as a resource
In cases involving interaction with the SCDoc markup language & syntax, my instinct would be to reference an existing help document with similarly-structured content, and model any changes after it. The help documents you reference are certainly relevant, but I have relied on them minimally, in some cases not at all.
I know there’s a lot of discussion currently going on here, and I’ll reference one of your posts from this thread:
With regard to the items you describe as “difficult,” my reaction is that computer programming, in general, is “difficult.” It took me many years before I felt confident using SC and navigating the docs. Also, difficulty is subjective. What is easy for some is not for others. One of the challenges of teaching, and of developing instructive materials, is that recipients’ learning styles can vary significantly. The primary goal of SC documentation, in my opinion, is to document the classes and methods that make up the SC platform, while teaching is more of a secondary goal. Of course, it is sensible and good to including “teaching moments” in the documentation wherever appropriate, and such moments already exist throughout the documentation.
With regard to items that are “missing / unclear,” more specificity would be appropriate. A tutorial or documentation item you’ve designated as “missing” might just be one that you haven’t found yet, because it is categorized in an unexpected way. It is challenging to make every piece of information easily findable, because so many concepts in SC are interrelated.
Extremely grateful for the reply… a tutorial on this subject in particular may be the only one to date, and it’s greatly appreciated.
The focus is making documentation contribution more accessible for users who are willing to do their share of the heavy lifting for SC’s future vision.
You make a valid argument regarding SC & it’s reference… the topic came from this survey , Question 11:
Apology accepted… you were very professional, considering you were under the impression that I had personally submitted a gripe list the size of the entire community.
I also mentioned over there, an sc script that would take those ScHelp index & render etc… used for an edit & preview workflow with a drop down “click to insert full list help syntax”… & ideally, a big submit button w/ git.
I think it would help enable some of us to pitch in… it hard to motivate doc updates to the community at it’s current phase… though we all agree it’s the issue outstanding.
There’s still 250 (core) and 500 (core+extensions) undocumented classes… if it’s sucn an unpopular task, then I think the task itself needs an update, some how… I think that’s why ScDoc.renderAllHelpDocs and the rest of those classes were written in the first place.
As a legitimate gripe, I’m still burnt out from spending over a week working on a script that would install every quark from the directory url, remove duplicates and fixing the bugs / typos… without git… I coudn’t get the script to work with git (conclusion: use Quarks.gui) … postponing all of personal etc. just to try and do something for the community… and so, I can’t see myself trying to build something like this workflow script, until late fall at best… I keep mentioning it because I hope either someone will be inspired to take the project, or, at least tell me it’s a bad idea, or can’t be done…
I would just like to again say thank you, you’re tutorial might be the only light in the dark here.
Also a little tip: @elgiano’s schelp-watch tool is quite handy in my opionion - it lets you see changes to help files “live” sort of.
Oh and yes, that tutorial of yours Eli is heaven sent!! Really great stuff to send off to new contributors.
I really can’t stress enough (and this isn’t aimed at you Rainer but at all of us) that the documentation is only as good as we the community make it. If anyone out there sees some help files that are lacking or in need of updates, I’d encourage them to change them. Newcomers to SuperCollider are especially valuable potential contributors to the help files since they haven’t yet made habits for themselves or found a particular place to find a particular piece of information but may still see with fresh eyes what is in need of work.
That said, I actually think SC’s documentation is quite good compared to a lot of similar projects’ (Max’ documentation by comparison is a nightmare in my opinion), although it constantly needs attention and there is a lot missing.
There’s a guide to writing help, and an reference for the help syntax, among the ScDoc classes, and a separate HelpBrowser GUI, included in the SC documentation.
To edit the help source in place:
SCDoc.helpSourceDir.openOS
// open, edit, & save .schelp
SCDoc.indexAllDocuments
// run index & reload help
…do we know of anything else or code that might be useful?
There’s also the Implementation search which provides easy and dynamic access to the source code for various objects and methods. That’s pretty handy, and I often end up forgetting about it, navigating the help browser to view the source code.
It’d just pop up the browser on the selected class, or the class at the cursor.
that’s exactly how Cmd/Ctl + D performs for me, just to be clear… it’s called ‘Look up Reference at Cursor’
I think the best option would be the ability to put a short SC script in the .yaml config file.
And from there… add new forms of behavior directly to the SCDoc / HelpBrowser classes.
You seem to know a few more good ideas in this area than I do, however, if no one does it first, I’m going to log the scripting ability for the .yaml config as a Feature Request sometime later on this week.
Completely off topic, but what does this method do? If I had to guess by the name it reconnects a previously booted scsynth instance, rather than make a new one and overwrite the previous? If so, I was wondering if there’s a way to do this after doing something that boots me off the server!
Extremely grateful for the reply… a 