How to make Help/Reference files for custom abstractions?
I understand that I can save a file as .maxhelp, but I'm looking for more documentation and tips for making the references and anything I can do to make my custom abstractions better documented.
Can anyone point me in the right direction on this? Thanks!
The first step would be to pack your abstractions into a package. If you take a look at other packages you will see how it’s done. A help file e.g. is a Max patcher, saved under the same name but with the extension .maxhelp inside a folder called help in your package.
i dont think there are guidelines for helpfiles, but as a minimum you should show off everything you might forget yourself after a few years, and in the optimal case you would show off everything the objects can do.
personally i would not use tabs like they do for the factory content but put everything in a single canvas.
what can be most useful is to explain in a few words what it is intended to do, like "this is a math function" or "this is a helper file for making UI objects in lcd".
eventually you also want to choose a custom design for all your stuff.
Thanks for the replies so far. My abstractions won't be distributed, but I want to document as close to the Max native documentation as possible for (my personal) ease of use.
For example, I have an abstraction called coin-toss which gives a random bang from one of its two outlets. The left inlet takes a bang or a seed message. The right inlet and/or creation argument accepts 0-1 float to determine the probability that the bang will go to the left or right inlet.
I want my documentation to have all the same features as the native [decide] (or at least as many as possible) and I can't find any documentation about how to populate the reference. I can make the help file show up, but I don't understand how [decide]'s help "header" file is built. Right clicking on it gives me options to "Open jsui Help".
I write JS professionally and I'm familiar with Pd. I just can't seem to find anything that walks thru creating help/reference files. Specifically I'd like to know how to edit the "default" formatting so I could copy a similar help file and modify and how to make the reference show up (including the tooltips you see when hovering over each inlet).
Update: https://docs.cycling74.com/max8/vignettes/assistance_authoring
This takes care of the "tooltips" which are properly called Assistance messages (and show up in inlet/outlet inspectors under Behavior/Comments)
the reference is not related to the help file and i dont think that the short form reference visible in the inspector row is very useful. for some stock objetcs there are 5 out of 15 functions shown^^
Thanks, Roman! I understand it's not related, but is it possible to make reference files for abstractions?
I really like working with Max, so I'm hoping to keep everything well documented and ironically one of the more difficult things I've run into so far is understanding how to write documentation. The concepts are a bit complicated and it's not obvious to me why the Clue window is treated separately or why it's useful.
i´ve never thought about that.
the "real" reference is probably html files within the app bundle, but i have no idea what makes that subset on the right side of the help window.
i also dont see a matching folder name among the default packages folder names.
You can create a ref file for your abstraction. For examples, look into /resources/docs of the Max app folder.
I don't think these are created manually at C74, but I don't know of a tool that comes with Max to create a ref file.
whenever i open a help file in modern max versions, i miss the inspector.