Less of a code suggestion and more of a documentation suggestion.
The way I personally find it easiest to program is the “find the pattern” method. Basically, I’ll come up with an idea of what I want to do and then try to find examples of something doing that thing. I think it would help out if the docs could include some examples in the form of links out to scripts or maybe even commits that implement certain features or do certain things. For example, I think this kind of thing is super useful:
I’ve been thinking of doing something similar for showing how to work with note states in the new clock system (clock.run with params, clock.sleep for note length, using a counter (and why you need it) to hold note states maintaining a buffer of on notes, etc.). i.e. this snippet which I’m still making sure is solid first
local noteCounter = 1
local heldNotes = {}
function pulseNote(freq, gateLength)
local currentNote = noteCounter
noteCounter = noteCounter + 1
engine.start(currentNote, freq)
clock.sleep(gateLength)
engine.stop(currentNote)
end
function playNote (noteNum, gateType, cur)
local freq = MusicUtil.note_num_to_freq(noteNum)
-- print(cur.nextStep .. ':' .. cur.nextStage ..' - play note ' .. freq .. 'hz of gate type ' .. gateType)
if gateType == 'pulse' then
clock.run(pulseNote, freq, cur.gateLength)
elseif gateType == 'hold' then
local currentNote = noteCounter
noteCounter = noteCounter + 1
table.insert(heldNotes, currentNote)
engine.start(currentNote, freq)
end
end
function stopHeldNote ()
local noteToStop = table.remove(heldNotes)
if noteToStop ~= nil then
engine.stop(noteToStop)
end
end
Maybe we need a place to house this kind of stuff that’s not just threads on lines.
And I will say I, love the procedural style of working with lua in norns/crow that a lot of scripts use. I wish engines were the same…every time I try to open a supercollider file to make some change I end up closing it more confused than when I started 
EDIT: one more reason I think this could be good is that it could make it easy to find the most up to date way of doing things (provided the docs are kept up to date)