Writing Help: Workflow

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.

These classes do most the work for you:


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.


:wave: 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:

Ah, apologies, my mistake. I mistook those survey responses as your own personal thoughts.

1 Like

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.

With all due respect, thank you.

The writing help help file has recently gotten a small cleanup but could definately use more work if anyone feels like adding to it.

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.

Oh and for those using (n)vim: These snippets greatly speed up writing help files


So far, our resources include:

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:

// open, edit, & save .schelp
// run index & reload help 

…do we know of anything else or code that might be useful?

A nice thing that is possible in the SCIDE is if you open a help file and scroll to the bottom you can click the link to the help file to see/edit it.

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.

I agree, “Implementors of” (Ctl-i) is a very nice way of getting about.

And it has an excellent implementation.

It would be nicer still if method documentation was written in the method definition!

“Senders of” (Ctl-u) is very helpful too, since you can easily find how a method is actually used.

It’d be nice to have a keybinding for .browse (maybe Ctl-b?)

The Browser implementation could be tidied up a little bit.

For instance, it’d be nice if it had the traditional pane to show the selected method source.

A good code browser is a very nice thing!

Cmd/Ctrl+B is boot the server !

So far:

  • Cmd + D -> search the docs at cursor
  • Cmd + Shift + D -> opens a new doc search

…in my config, and maybe default.

How would .browse work, in this line of thought?

Or a surrounding feature that would prove useful, perhaps.

Cmd/Ctrl+B is boot the server !

Hmmm… It’s not here? (3.11.2, defaults, I think…)

But oh well, some other key then? (It’s C-b in Squeak…)

How would .browse work, in this line of thought?

It’d just pop up the browser on the selected class, or the class at the cursor.

The same as C-i and C-u do for methods.

The other command I find very useful is “Inspect it”, maybe that’s worth a keybinding?

How would .browse work, in this line of thought?

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.

that’s exactly how Cmd/Ctl + D performs for me, just to be clear…

Ah yes, but that looks it up in the Help browser.

By .browse I meant the Class browser, ie. what you get if you do Class.browse, for instance.

Ps. And likewise, by “Inspect it” I meant the Object inspector, ie.

{arg freq=110; SinOsc.ar(freq)}.asSynthDef.inspect

Pps. I’m not quite sure what you mean about the scripting, is it related to this?


Which, I think is also connected to this:


Pps. Looking for the above, I stumbled on this!


Cmd/Ctrl+B is boot the server !

Hmmm… It’s not here? (3.11.2, defaults, I think…)

Actually it is, sorry!

I can’t see it though because I do s.startAliveThread in a startup file.

So the menu entry disappears and Ctl-b doesn’t do anything.

scsynth is amazing, it just never crashes!

Anyway, that was the mystery.

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!