Documentation structure / organisation

[yaxu]

A few thoughts while looking through the documentation.

• it's excellent !
• 'sounds' could come before 'notes', as more general and easier to understand for someone who doesn't read music
• 'syntax' is maybe a bit heavy for non-programmers. It could come after some more example-heavy motivating stuff, or there could be a note to say you can skip ahead and come back later if you want to stay more hands-on. I'm just totally guessing though, would be good to get some feedback from learners
• 'mini-notation' - a lovely intro, just wondering again if sounds could be used instead of notes for this. A bit easier to see/hear the difference, and in general I think drums are easier to hear rhythms without melodies confusing things (might be a personal thing)
  • Parallel/polyphony - could do with an example of other use of this besides chords, e.g. polymeter
  • Mininotation review - there's an _ in the example that works in tidal but not strudel. I think @2 is intended here
  • euclidean explanation is really excellent!
  • {} polymeter syntax is missing
• Samples - love the detail, but there is some assumed knowledge around github, repos, wav files, etc. I feel a non-dev musician coming to this would appreciate a bottom-up step-by-step explanation about how to get a sound into strudel. I'm not sure what the easiest way to do that would be though, when it involves somehow exposing the sounds the web.
  • There aren't many sample-only controls, and chop is misplaced here. I would mix sample-only and general audio effects under a single 'effects' page, and move chop to a 'sample mangling' page or section along with splice, slice and striate.
• Synths is short, maybe 'csound' could be merged there? Also a additive synth example with the default synths would be nice
• Audio effects - we should make a compound adsr control !
  • 'gain' and its explanation might be jargon for some, add the word 'volume' somewhere
  • 'room' sounds cool with numbers over 1. maybe we leave this as an easter egg..
• Introduction
  • 'Functional javascript API' - I think these will be three quite unfamiliar/scary words for some and we could just use the title 'pattern functions' and avoid mentioning javascript or APIs outside of parts addressing people who are already programmers. (Also strictly speaking, I'd say strudel isn't an API.)
• I like to avoid words like 'powerful', alternatives like 'expressive' and 'easy' are friendlier
• Time modifiers
  • Maybe 'Time manipulators' or 'Time patterning' ?
  • Some like euclid, ply feels like they don't fit here. Could be on a 'time structuring' section or page along with struct etc? Or would fit better if we rename this section to 'Time patterning' as a more general term..
  • inside/outside could have better explanations. I think they're underexplored in general..
  • ribbon - typo at > an
• Control parameters
  • We didn't call them 'control parameters' in the earlier effects section. Would be good to standardise the terminology a bit. Also here sometimes we just call them 'params'. TBH I think there could be better words to describe these things but have not found them myself yet!
  • Seems assumed people know to look in the javascript console to check the log() output here? Many people won't know how to do that
  • 'Patterns of plain values can be modified with any of the following operators:' Only one is shown, the list comes a bit later
  • custom parameters - an example of creating multi-param controls via mininotation lists could be nice
• Continuous signals
  • sine2, saw2 etc could be given more prominence here, with an example of their usefulness in multiplying/adding together to make more complex signals.
  • random signals could be a separate page. The random 'modifiers' don't belong in a signals section. so could have a 'random' page which follows the signals one and starts with random signals.
  • I don't really like the word 'modifiers', maybe 'transformers' or 'patterners' or in the context of randomness 'randomisers'
• Conditional modifiers
  • Again I think there could be a more descriptive title, and actually many of the functions don't fit here. I feel we need a post-it for each function and re-organise them all into new categories..
• Accumulation modifiers
  • Just 'layering' would be a better title
• Tonal API
  • Again I think 'API' isn't the best word here. I don't think most end-users need to know which library they came from, that could just be a credit at the bottom. This could be moved up under 'notes' or renamed 'Note manipulations' or something
• More
  • maybe could be renamed 'advanced topics'
• MIDI & OSC
  • add new cc compound control
  • SuperDirt API - rephrase/expand to be clearer for people who don't know what tidal is, maybe drop 'API'
  • Pattern alignment - as this matures, this could move up into the main tutorial

My main feeling is that I think the functions could be more accessible if we reorganised them under more descriptive headings, which I think is quite a big task. Maybe we could use miro or something for that.

So that was the first time I've looked through all the docs and it's excellent! Really comprehensive. I can have another pass addressing some of the above but I thought I'd give others a chance to respond to my scrappy notes first..

[felixroos]

'sounds' could come before 'notes', as more general and easier to understand for someone who doesn't read music

agreed.

'syntax' is maybe a bit heavy for non-programmers. It could come after some more example-heavy motivating stuff, or there could be a note to say you can skip ahead and come back later if you want to stay more hands-on. I'm just totally guessing though, would be good to get some feedback from learners

agreed.

'mini-notation' - a lovely intro, just wondering again if sounds could be used instead of notes for this. A bit easier to see/hear the difference, and in general I think drums are easier to hear rhythms without melodies confusing things (might be a personal thing)

the problem with sounds right now is that there is not a nice way to visualize them in the pianoroll, because they have no pitch. with notes, the pianoroll is an additional aid in understanding. If we find way to visualize sounds automatically (maybe also label them), it would have a similar didactic quality. Maybe it's also a good idea to just give examples for sounds and notes not only one of the two.

Samples - love the detail, but there is some assumed knowledge around github, repos, wav files, etc. I feel a non-dev musician coming to this would appreciate a bottom-up step-by-step explanation about how to get a sound into strudel. I'm not sure what the easiest way to do that would be though, when it involves somehow exposing the sounds the web.

Yep.. there is a general problem of approachability vs documentation completeness. The samples page is currently more written as "these are all things you can do with samples". I am not sure if it is even possible to give a complete picture while also being beginner friendly.. maybe the beginner friendly tutorial just has to omit stuff, but then we practically need 2 pages for the same thing

Synths is short, maybe 'csound' could be merged there? Also a additive synth example with the default synths would be nice

The soundfonts could also land there now. not sure about csound, as it's still experimental and maybe a too deep (and experimental / not fully integrated) feature to present here? I can even see csound being moved to somewhere else for now

Audio effects - we should make a compound adsr control !

#541

Introduction 'Functional javascript API' - I think these will be three quite unfamiliar/scary words for some

totally agree.. I also think we should be frugal with dropping links in the introduction as they can distract people, especially if you're not used to having 2000 tabs open. the introduction should rather get you focused.. we have a total of 18 (!) links on the introduction page. The very first sentence contains 4 things that the average reader does not understand:

• live coding
• web-based implementation
• TidalCycles
• algorithmic pattern language

In an earlier version of the tutorial, the introduction sentence was:

"With Strudel, you can expressively write dynamic music pieces. It aims to be Tidal Cycles for JavaScript.
You don't need to know JavaScript or Tidal Cycles to make music with Strudel.
This interactive tutorial will guide you through the basics of Strudel.
The best place to actually make music with Strudel is the Strudel REPL"

this is just my feedback for the first half of the discussion

[jarmitage]

Samples - love the detail, but there is some assumed knowledge around github, repos, wav files, etc.

My sense is that the current page documents the current process well, but that the process itself still needs more streamlining to be more user-friendly. There's only so much the docs can do to describe what is currently a fairly complex process.

[jarmitage]

My reflection from the workshop yesterday is that we have a strong technical foundation, and it would be great to supplement this with more musical inspirations and examples. Similar perhaps to the examples in the main REPL but simpler and broken down.

Similar maybe to this, where you can just run bits of code and follow your ear https://github.com/tidalcycles/tidal-workshop/blob/master/workshop.tidal

[felixroos]

yes, right now, most examples are more functional and minimal, totally need some more inspirational / artistic / musical bits. i wonder if it makes sense to have a dedicated workshop / course page(s), or if it should appear in the main doc.

[felixroos]

i am doing a strudel workshop in 2 weeks, big overhaul of the tutorial incoming...

[felixroos]

just created #587 where some of the points here are addressed.

the general idea is that it might make sense to have a workshop that is non-exhaustive but practical and fun, giving you a minimal set of tools to make music. the rest of the docs is exhaustive but more referency.

'sounds' could come before 'notes', as more general and easier to understand for someone who doesn't read music

done

'syntax' is maybe a bit heavy for non-programmers. It could come after some more example-heavy motivating stuff, or there could be a note to say you can skip ahead and come back later if you want to stay more hands-on. I'm just totally guessing though, would be good to get some feedback from learners

For now I've moved the "Coding Syntax" chapter to the More section.

'mini-notation' - a lovely intro, just wondering again if sounds could be used instead of notes for this

The workshop starts with sounds and also teaches mini notation in the process, so this is fixed. The old Mini-Notation is now in the More section, acting more as a reference. It could still be overhauled a bit with sound examples.

Samples - love the detail, but there is some assumed knowledge around github, repos, wav files, etc. I feel a non-dev musician coming to this would appreciate a bottom-up step-by-step explanation about how to get a sound into strudel. I'm not sure what the easiest way to do that would be though, when it involves somehow exposing the sounds the web.

still tbd, as mentioned in the PR, there should be a step by step guide for a) using samples from disk (using samples4web) b) using samples online (github?). The old samples page could still stay but acting more as a reference

Audio effects - we should make a compound adsr control !

done

'Functional javascript API' - I think these will be three quite unfamiliar/scary words for some and we could just use the title 'pattern functions' and avoid mentioning javascript or APIs outside of parts addressing people who are already programmers. (Also strictly speaking, I'd say strudel isn't an API.)

the new intro page now uses less jargon buzzwords

I like to avoid words like 'powerful', alternatives like 'expressive' and 'easy' are friendlier

done

@yaxu @jarmitage What do you think about the general direction I'm going here?

It's still a lot of work to get everything into its proper place, but I think it's a start..
I also want to make a cut here because I am giving my workshop this weekend, so maybe it makes sense to deploy it in the current state and do another round of later.