Rather than everyone sending individual emails to the team, I figured it might be easier to kind of put this all in one place.
-in all the example files @attributes are shown in camel caps (i.e. startChan) but in reality it is case sensitive and it wants all lower case (startchan)
-the -1 for fftsettings is used all over the place, but never explained (or at least I’ve never come across it)
-all (complex) examples need a paragraph (in the top right) that explains what the patch should be doing
-the bird finder patch has lots of elements that invite engagement when they shouldn’t (i.e. the toggle switch for detection which is just a display item, and not a toggle to enable “detection”)
-(root) in helpfiles is weird and easy enough to change
-bigger help files should scroll down (or right (but not both))
Thanks for collecting these together @rodrigo.constanzo. I’m embarking on an overall review of the Max helpfiles today, which will (necessarily) be entangled with beginning to bring the maxref xml up to par as well.
Yes. This is because this content has been provisioanlly populated from the Supercollider references, where everything is camel back. This is trivial to fix. Idiomatically, of course, we’d expect this information to be available from the inspector reference (in short form) and the reference file proper in more detail. However, @tutschku did say that he liked having this stuff to hand in the help file, so we’ll return to the subject of what information and how much should be in the help file in a later thread (I intend to pull it in dynamically from the xml via js, like C74 and bach do).
-the -1 for fftsettings is used all over the place, but never explained (or at least I’ve never come across it)
It seems like, as well as an overview patch, we need a central reference for some of these conventions.
Agreed. I think some of the more complex examples might also be destined to become separate example or tutorial patches separate to the help file.
We can have some fun refactoring this. I think the elements in the patch have the basis for some more generally useful UI elements, so perhaps @tremblap and I can review them, looking at the potential for reuse.
Yes and yes.
I think the baseline help patch size for built-in objects is 700x500, which is small (e.g. poke~), but some are bigger (e.g. dict~). Seems like a good range of sizes to aim for?
Yes, this is a convention that needs documenting.
-1 is a contextually dependant default, i.e. pick some sensible default value where the actual number involved depends on some other factor:
for values where you’re specifying some range of a buffer (either frames or channels), -1 means all the things.
for fft settings (whose order is window size, hop size, fft size) , -1 hop size => window size / 2, -1 fft size => window size.
The idea here was to find a way of having sensible defaults that will cover most situations, but to leave room for tweaking where needed.
Here is a list of other things that you guys said that I took notes on, and/or snags that you hit and my solutions to them. Feel free to comment/nuance if I misread you:
@tutschku asked for not using the ‘preset’ object, as it does not behave in copy/pasting test patches, but to go forward a more ‘dictionnary’ based approach. @weefuzzy should be happy about this, and I’ll have to learn that syntax but I can see the benefit.
you all asked for a curated set of (fft) settings in each file. Instead of having a musician intention mapped to fft, I’d do the other way round. For instance:
(buf)pitch: small windows (128) will be good for time accuracy at the cost of pitch precision. Large windows (8192) will be slower and slopier in time, and will induce cpu-spikes instead of a steadier heavy load, but much more precise in the pitch tracking.
I have to say that since this is almost true for everything, I forgot to write it in. Instead, we’ve put an attrui everywhere, and more importantly, we’ve made it modulatable in real time (by opposition to pfft for instance) so it can be tested in context. But I think a quick one-liner could be helpful for our favourite settings, and/or for various observed behaviour of given parameters?
an irritant is that most buffers are not named with a name that echoes the parameter and data in contains. Sticking to them, seems important to understand and get the vocabulary, and I heard you. Also, one irritant for me is that most helpfiles have the same source buffer name which makes it complicated to have more than one opened at a time (cross talk!) so we will need to think about a naming method that is unique to each object patch too.
FFT helpers:
I don’t think we were talking about these very obvious oppositions 128 vs. 8192. Those should be known. I guess in experimenting with the different algorithms you came across settings which work better than others, including the relations between FFT size, hop size and window size. I know we can all experiment with them, but an explanation from your experience WHY you chose certain combinations of the three parameters PER algorithm - paired with audio examples would be helpful .
buffer names:
what if you keep the parameter as ‘main’ name for the buffer and append ‘nmf-tutorial-1’, '‘nmf-tutorial-2’, etc.
I think this will make it explicit, which parameter we are talking about AND tell the user that those are specific to THIS patch. A hint to alter those names for his/her own use might be helpful as well.
Totally, that’s a great idea.
My initial comment was more about how the patching inside the helpfile flowed, when it was more than “one n sized screen” big. Some examples have more patch below it, and some have more to the right. That’s more what I was talking about.
I’ve mentioned some of this stuff to @tremblap, and had a tiny chat with @weefuzzy the other day about it, but the structure of the helpfiles can be made much clearer and cleaner too. (not opening with a “reference” tab).
There should be a simple and clear example, and each tab should get progressively more detailed and/or complex. And I’m not sure that didactic vs musical (are those even different things?!) are categories that should be used in that there’s no reason why the initial simple/clear/concise example can’t also be musical.
Like the first tab shouldn’t use many @attributes and instead use default settings, then in subsequent examples you expose for the complexities etc…
I actually think that opening with a reference tab is not a terrible idea. These are complicated tools that don’t have a single function and are flexible and modular. Opening up to a dumbed down example is not particularly conducive to exposing the possibilities of the objects, which I think is important, given that this is aimed at people who should know a bit about DSP and are going to use them to push the boundaries.
I’m going to present a dogmatic example of how I think the help files could function. I don’t mean to present this in a patronising way, more that this presents some of the things I really like about certain packages and how they communicate information/parameters etc as well as what I’ve learned from putting together FrameLib stuff.
N.B I didn’t adjust mode 1/2 only mode 0 to demonstrate how simple a file should be (at least to begin with).
Things that I would like to see…
Discussion
I think a discussion of more complicated concepts such as implications of FFT size (beyond resolution and stuff people who this is target at should know) and certain attributes such as @numiters in fluid.nmf~ is definitely necessary in an appendix tab of each help file. This should cover edge cases as well as a link to the knowledge exchange and perhaps even discourse. This could promote discussion and people to reach out.
Ergonomics
The patchers should be as sparse as possible without hiding information or making things short form. Throwing a block’o text at me makes me freak out and I immediately switch off at that point. This particularly ‘grievance’ has been made known multiple times but I think that its not the information itself that is an issue, but the way you navigate it as a user. Complicated discussion up the back, light introduction with navigatable info in the front with increasingly complex examples as you move through the tabs. A reference mullet i think is the official term.
Scaffolding
I think in some examples the patchers that exist now tell too much in one place. There really should be a latency sub patch/tab for every object that incurs latency or at least how you would patch around it. I’m pretty sure the user is aware that if you add your delay signal to your original with the right compensation and -~ you’ll null sum. I don’t really care about this. Perhaps there should be a vignette in the package like ‘Adjusting for latency in the fluid composition package’ which explains using getattr or a message to compensate. My point here is, every patch doesn’t need to show you how to compensate for latency and it just confuses the user, especially when its the first thing you see. Same goes for the difference between didactic and musical. I don’t think this kind of differentiation makes sense at all as something can be both didactic and musical to demonstrate that a = b. I think in most cases didactic actually == simple, and musical == complex. In other words, this info can be communicated by having an appropriately scaffolded level of difficulty across various tabs.
It goes without saying that a lot of my thoughts around how a help file should look are @tremblap’s feedback as I made FrameLib.
Except the speculative ‘individual object’ helpfile.
I think what you’ve setup for fluid.hpss~ only really makes sense for a package/library overview (ala BACH, HISS, FrameLib etc…), but in your helpfile, I’d have to click each individual attribute to to find out what they do.
I do prefer a more “standard” helpfile (the slow exposition of most .maxhelp), but it isn’t setup for a heavy user. That being said you can always just directly go to the reference file if that’s preferred.
Thats my thinking also - help is for quick reference and becoming familiar with the object. The max reference is where you go for detailed information, or the right panel when it expands as this just pulls the same data.
I just meant your example of what a single object what might look like. Unless I misunderstood.
So in something like BACH (et al) you have these umenu’s which bring up different views and bits of info, and that’s quite handy. But I don’t think it works well for an individual object helpfile.
Bottom line is, I think that there should be info on the stuff but not in its current state. This is one approach to making it smaller and more digestable if the user wishes, or ignorable if theyre not interested. I think we’re on the same page though.
I like this. A lot. It shows the extent to which it is hard to find a help/example/reference/furtherhelp paradigm that is right for our users.
keep on sending the comments, we’re all ears. And when we discuss back, it is both to understand more, and also to explain more the pros and cons of each decisions, which allows us to make sure we got it right for most people most of the time…
The new helpfiles are amazing. Super fucking helpful.
There a bunch of inconsistencies in places, like no info on the 2nd tab of fluid.noveltyslice~, lack of caps in 3rd tab of fluid.bufnoveltyslice~ and many other objects (fluid.bufnmf~), but the main reason for my bump is the sfplay~s in nearly every object.
The umenu shows Nicol-LoopE-M.wav (because it is the first entry), but it is not loaded, which is unintuitive says the visual state indicates it is loaded. Since it’s an embedded subpatch just check a t b l after the prepend prefix so it loads the first file by default, and more importantly, bake an open message into the helpfile(s) so it’s more easy to test with other files.
Same goes for the buf-based ones. Having a replace in there would be super useful.
Glad you’re finding them an improvement. When you say ‘lack of caps’, can you elaborate?
As for sfplay~ gripes, yes sure, we can
trigger open a default example file
put open and replace messages into the top level patches
It had been (maybe still is) my ambition to hack C74’s demosound patch for our needs, because it’s ubiquitous and many-featured. For some reason, they didn’t make it so it that it’s easy to point to a different directory of audio files, hence the need for some hackery.
Sorry, I meant capitalization. It’s super inconsistent across the text with some being: “A sentence.” and others being “a sentence”.
Yes please, I’m a big fan of the demosound.
If at all possible, it would be great to have both directories in the umenu there, since it’d be easy/good to compare against the classic files that people know.
if you do hack demosound@weefuzzy please make the loading volume 0.0db and not -20db. The slider is so finnicky to get right and the reset to 0 option only sometimes works (for me at least). I pretty much always want 0 unless the gain is post and the monitor is pre. Please!
