I think a lot of it is down to two issues:
- being time pressed
- methods of learning
So if the information is not laid out as the reader naturally conceptualises then they must put in some effort to find the framework of understanding - and that's what I did and I wound up not finding it in the manual but in a Youtube video.
I agree that a Practical examples would help as an addendum, but I think that an
introductory chapter with stronger fundamentals would help people like me.
I think that the Overview section needs to explain the concepts and terminology in a more straightforward manner.
EXAMPLE OF HOW THE INTRODUCTION COULD FRAME THE CONCEPTS
Clyphx allows you to trigger special scripted actions in Ableton Live ranging from the simple to the complex. You can attach actions to clips, to arrangement locators, or to buttons and dials on your hardware midi controller ( and more)
This flexibility means that when you click a ClyphX clip, or turn a hardware dial to which a Clyphx script has been assigned - you will be able to trigger your own scripts built up of Actions, and Clyphx Actions can be chained to produce complex results.
Examples include :
<list>
More examples are available in Appendix A
--------------------------
Now, you might say ... that's pretty much what's in there already, but it's not how I read it
Explanation of how I read the existing manual
I will explain my interactions with the manual and detail how I read it, and how I interpret it ... leading to me not understanding it
The ClyphX manual I have to hand is 2.4.9
For the broader conceptual picture I would look for
Getting Started, and hope to find in that section (or once near it) something which matches my experience.
So, if there were the words "and we use ECMA script ..." I'd know what experience to call on, or if I saw the words "Like Live's Macros ..." I'd have a completely different understanding of how we were about to conceptualise this interaction.
So, lets look at
Getting Started. The contents focus on running a quick HELLO WORLD script. So, it's more of a technical "getting started", so I've not found my conceptual overview here. So, I think - Lets try the next chapter.
OVERVIEW
ClyphX provides an extensive list of Actions related to controlling different aspects of Live. You can
access these Actions via X-Triggers. There are currently four types of X-Triggers:
- X-CLIP – Any Clip in Session View with the appropriate naming convention.
- X-CUE – Any Locator in Arrangement View with the appropriate naming convention.
- X-CONTROL – MIDI Controls.
- STARTUP ACTIONS – This is an event that will be triggered each time a Live set is loaded. This
is specified in your User Settings.
Ok, so this seems to be the section where we define the conceptual framework
It tells us, there are actions, and there are something called X-Triggers. of which there are 4 types.
I think to myself "what is an X-Trigger, is this a Trigger but better? What is a trigger? In Live are there 'triggers'? no, so why are these X-Triggers?"
slightly confused I continue looking for an expansion, and notice that the X-Triggers is a link, so I click it.
which takes me to
X-TRIGGERS
X-Clip
As mentioned in Naming Conventions, in order to turn a Clip into an X-Clip, you’ll need to add an
Identifier to the beginning of the Clip’s name.
There are several types of X-Clips:
DEFAULT
Example: [ID] CLIP SEMI > ; CLIP CENT -25
So ... what are X-triggers?
I go back to the OVERVIEW section looking for the first example of a trigger to see if I can work it out from context, the first example is - X-CLIP – Any Clip in Session View with the appropriate naming convention. The link is hot, so I follow it to the following section
X-Clip
As mentioned in
Naming Conventions, in order to turn a Clip into an X-Clip, you’ll need to add an
Identifier to the beginning of the Clip’s name.
There are several types of X-Clips:DEFAULT
Example: [ID] CLIP SEMI > ; CLIP CENT -25
This X-Clip will perform its Action List when the X-Clip is played (not launched). This way, Action
Lists can be quantized via Global or Launch Quantization.
....
Ok, so now I click on "Naming conventions" and read that , the come back to Clips again ... still looking for my conceptual model.
There isn't one, but there is an example
Example: [ID] CLIP SEMI > ; CLIP CENT -25
I try it and it works, so by now I think I may be on the right track, even though I dont yet have a mental model of the system.
I go looking for "Preset Snapshot" , which is what I need. The PDF search turns up nothing, scanning through the doc turns up nothing so I turn to google
which takes me here
https://www.youtube.com/watch?v=FGBQw6tn0Rg
and I try that and it works, and THAT is where I stopped reading the manual
-----
So, I'm aware this is all tl;dr
so tl;dr
the manual never sets up the conceptual framework for some users to build a coherent mental model, so I found a youtube video with a recipe and then followed that for the previous 4 years.