Documentation Improvements
As I continue my journey into learning Max/MSP, RNBO and gen, I wonder if there are any plans to improve the documentation, because frankly... it isn't good :(
Some examples (mostly gen specific, but pretty much applicable everywhere)
What do the objects output? Is it 0-1, -1-1, something else? Who knows?
What does the FFTInfo object output? The documentation says it provides "very useful information". But again, no documentation on the outputs. Great, what is it? From Graham's examples we know what output #2 provides (the FFT frame size) but that is about it. I assume it is hop size and other fft constants, but I don't like to assume things.
Why are there so few hyperlinks? I'm looking at the EXPR object for gen and it says "See the GenExpr documentation for more details" Great. Let me click on that to see those details.
Don't get me wrong, I think Max/MSP is pretty amazing but after so many years and an acquisition by a big company, I'd like to think some resources could be dedicated to this.
Usually hovering objects outlets with the mouse (when in edit mode) give you info about the output:
In addition to that, most objects reference page have an 'Output' section describing the various outlets. Here it is for [fftinfo~].
Why are there so few hyperlinks? I'm looking at the EXPR object for gen and it says "See the GenExpr documentation for more details" Great. Let me click on that to see those details.
This is specific to gen/gen~/jit.gen/jit.pix/jit.gl.pix objects which inner objects are more like functions than actual objects and have a small help popup bubble instead of dedicated help file and reference page.
However, if you click that little manual circled in red, it sends you to the Gen Overview documentation page.
That page itself takes some time to mention and link to the GenExpr page, but the documentation hierarchy in the left sidebar leads you to it quite easily (as well as pages with the description of all operators):
This said, a link straight to the mentioned page or section in these small help popup bubble in gen patchers would definitely be helpful.
So,
that is great you found the fftinfo page. How did you get there? Because I googled - nothing.
If you right click on fftInfo and click fftInfo reference you get: (note there is no mention ouf outputs)
fftinfo
Report FFT constant data about a patcher loaded by pfft~
Description
fftinfo gets constant data about the FFT frames in a patcher loaded by pfft~. If it is used in a patcher that is not loaded by pfft~, it returns default constants instead.
But your other comments point out the problems with the documentation. If I am in gen, the expr reference does not give that little box above. And come on, Hyperlinks are a thing! If in gen it says "see genExpr documentation, then that should be a link I can click on.
There are sooo many examples of better documentation
This whole thing reminds me of Stockholm syndrome where people rationalize "yes, everything is fine".
There is a ton of room for improvements
that is great you found the fftinfo page. How did you get there? Because I googled - nothing.
My bad, I didn't realized you were talking about the fftinfo gen object. Actually, I wasn't even aware of its existence, and I didn't know gen objects/operators could have their own reference page.
I thought you were mentioning - and I was referring to - the regular [fftinfo~] Max object, which has a much more detailed reference page.
If I am in gen, the expr reference does not give that little box above.
To me, it does. Not sure I get you here. The help popup box is even specific to gen I think. And the outlet info box when hovering the outlets works both in Max and gen patchers.
And come on, Hyperlinks are a thing! If in gen it says "see genExpr documentation, then that should be a link I can click on.
There are sooo many examples of better documentation
To me it's more like a gen-specific documentation problem, which I admit is not as convenient as the regular Max documentation. It is kind of its own patching sub-system and the documentation reflects that by being less descriptive and with more UX friction than for regular Max objects. At least it is my feeling.
You can consider most gen objects as doing the same as their Max counterpart object, when there is one (like for most math operators, expr, fftinfo, or cartopol in jit.gen/pix), and checking the doc for the Max object can give more info than for the gen ones.
I remember struggling a lot to understand how sample, nearest and nearestpix from jit.gen/pix works because they don't have regular Max object equivalents, and they have no help file, and just a few lines of text from the help bubble is not enough to understand how they work unless you are already familiar with the concept of sampling. This reflects well the kind of friction I was talking about regarding documentation in gen.
There is a ton of room for improvements
There is always room for improvement for an always-growing software. The overall documentation actually had a lot of beneficial refinement (in my opinion) with Max 9. But I recognize the gen part of it hasn't gained much, if anything. Especially because of less detailed reference pages and the lack of explicit, visual examples like the helper patch could provide for regular objects.
Thanks for your kind reply, but lets be honest... gen has been around for over, what? 10 years?
Clearly they have had time to improve pages like this:
https://docs.cycling74.com/reference/gen_dsp_vectorsize/
sigh
+1 to gen docs needing improvement(it does linger in this 'sandbox' state that is very different from the rest of the docs of Max/MSP/Jitter for decades).
I am also a bit upset that i have to pay for a book like "GO", it's as if all these little elite tricks are hidden behind further paywalls. But it is a good book, so i don't make that a huge deal... (however, given the gen~ docs are so bad, it forces us to pay into this elitist hierarchical division of informational access in order to use gen~ effectively).
I'm a proponent of "don't attribute to malevolence to that which can be blamed by incompetence" so I don't think there is some nefarious scheme, they just don't seem to prioritize this very much.
About the book though, there are lots of references to "Book 2" in it, wonder if that will ever come out
"don't attribute to malevolence to that which can be blamed by incompetence"
fair enough, but any incompetence that gets practiced over the long-term, turns into a purposeful blind-spot, which can be considered, at that point, quite malevolent(has anyone made reparations for the transatlantic slave-trade yet? meanwhile, more civil-rights violations occur against that same diaspora long after that, and world-leaders are warring against each other with tariffs thinking they are being treated unfairly, while they themselves, won't pay reparations for those older unfair transgressions... but i guess i'll just apologize now for digressing: (mis)documenting gen~ is not the same as enslaving an entire race, no matter how purposefully-kept-in-the-dark i feel, and no matter for how long that feeling lasts).
wonder if that will ever come out
since they mentioned working on it here on the forums somewhat recently(like a month ago), i'm guessing it will be out within a year or two maximum(just my personal feeling).
you should see my new book about "135 ways to misuse the loadbang object" which i announced in 2001, but then sold it to behringer so that it now will be a little bit delayed because of some hong kong components shortage.
we call it "latency". meanwhile enjoy the announcement teasers.
you should see my new book about "135 ways to misuse the loadbang object"
HAHA! 🤣
sounds like my upcoming(will be released in the year 3000) book,
"Gen~ And The Art Of DevelopmentCycle Maintenance"
