Complete Operator Docs + Snippets

I think right now is a pretty important time for Derivative and TouchDesigner. The community and following has been really growing for the last number of years which is amazing, but at the same time there are now other players starting to take some market share such as Notch and the eventually upcoming Unity node editing pipelines. The big thing that will bring new people into TouchDesigner and keep them here for more than a few hours will be documentation and examples/templates.

This particular RFE has 2 parts:

  1. Every operator needs a set of snippets, even the most basic operators and especially for the advanced ones. When I started working with TD wayyyyyy back when, I honestly didn’t know what compositing meant because I came from a music background. So I naturally didn’t know what Composite TOP did. With a software that has so much breadth and attracts people from so many different industries, almost no prior knowledge can be assumed. Every. operator. needs. snippets.

  2. All wiki entries for all operators need to be complete. It’s been years that there are still operators with empty parameter definitions (even popular regularly used ones like OSC Out CHOP!). These things make a world of difference to new users, and they’ll reduce a lot of frustration in intermediate users who are often found tackling new workflows on every project. I’ve even noticed lately that existing operators that get new parameters or features added don’t have their wiki entries updated. A good example of this is the Local Address parameter of OSC Out CHOP, it’s completely missing from the wiki and I learned about it by scrubbing through some forum posts so that I could then teach someone else how to use it. To truly attest to how difficult the wiki is for most people, I have a paid workshop that people buy that basically is an hour long tutorial on how to use the wiki, some important pages on the wiki that are hard to get to, and how to find OP Snippets (most people don’t know they exist…)

I think a strong (and disappointing) example of the 2 of these combined is the nVidia Flow operators which compelled me to put this RFE together. Both operators (COMP and TOP) have completely blank wiki pages and there are no op snippets for either. How is anyone expected to figure out how to use it other than luck and wasting time with trial and error? In 2019, new users don’t have the patience or attention span for that when they’re picking up new tools. I would bet money that there have been new users that have opened TD, tried to use flow, saw the empty docs and no op snippets, and then closed the software and said “I’d rather use something else.”

As much as I love TD, I personally think this is unacceptable for something that really could be solved by some interns. How long would it take to make 2-3 snippets for nVidia flow? An hour? 2 hours? How long would it take to fill in the documentation (which could even be as barebones as copying and pasting what the parameters do from the nvidia flow documentation)? 5 hours? 10 hours? nVidia Flow was released as stable I believe at the beginning of May (and it was in development for a little bit of time before then I imagine), and 10-12 hours couldn’t be allocated to document what this is and what it does and provide an example or two so people could use it easily? It’s jaw dropping for me.

It may seem pedantic or nit picky, but as someone who teaches so much, these are the precise things that make TouchDesigner difficult to teach/learn and I constantly have to try to re-enforce with people I meet that are just learning TouchDesigner and feeling discouraged something along the lines of “I know the documentation has lots of holes and it can be hard to navigate, but if you have some patience and lean on the community you’ll have a lot of fun and success.” What kind of message is that to tell people? For those who’ve done a lot of teaching, they can probably tell you their experience when during a workshop you tell people they can figure out how to use an operator by hitting the question mark at the top of the parameters only to get to a page with lots of missing parameter definitions. It’s kind of embarrassing even for the teacher. Like what do we say? “Oh yes, this software is groundbreaking and there’s nothing like it, really, it’s been around for a while, but they kind of just don’t document a lot of stuff and you have to ask around.”

I’ve never met anyone in my life that has said says “Oh, I don’t use TouchDesigner because it doesn’t have enough features” but I’ve met countless people who say “Oh I don’t use TouchDesigner because it’s hard to learn and the documentation sucks.” Taking TouchDesigner to the next level I think will be through solving this.

Bump! Documentation and snippets are critical at this point.

+1 the situation hasn’t improved much since the first time I peeked at TD and ran away for two years for exactly this reason … documentation is the Single Source of Truth and should be treated like scripture. It should be meticulous and complete and authoritative.

That’s not an aspirational thing, it’s table stakes for a professional product. To have entire entries still stubs years after features roll out is a signal to newcomers that all may not be well, that the tool may be opaque and incomplete, and that Here Be Bugs.

I would imagine there is a reasonable way to script the publish process such that every update flags all affected doc entries ‘needs review’ leading to a pre-update QA process of re-consideration and editing of the documentation to reflect the ground truth. Kind of like doc unit tests.

This sort of thing leads to some frustration, even for intermediate users like myself - it means that while using built-in Ops as intended one frequently needs to halt the process to scour the forum for examples or ask the community for help, simply to understand the basic use of a native feature. That’s kind of crazy with a program that is adding features as rapidly as Touch is.

+1, especially the SOPS. Been using TD heavily since 2014 and still can’t figure out how to get a lot of the sops working properly.

I also would add that more in depth articles & quick tips on some of the mechanics behind TD would be good. Example: Time slicing has a dedicated article, but nowhere is mentioned the number one tip for timeslicing - putting a trim chop with absolute value 0 will ensure issues don’t ripple down stream for exports when frames drop.

What is the black magic you speak of? Please enlighten us! What does that accomplish? And I’ll throw in a +1 for sop docs too!

Excellent post and thanks for taking the time to make it Elburz. As a first step we plan to make a company wide effect to fill in all of the missing documentation in the wiki ASAP. Complete OP Snippets are also something we are working towards as well.

No problem. I’m not sure if the Wiki is part of the web upgrades, but I’m sure users would help if there was an easy way to tag stuff that isn’t finished and even fill out certain things that maybe are obvious/copy-paste jobs.

Yeah! Spot on!
And Some simple GLSL examples of what you can plug from TD into GLSL,
Or basic operations you can do in GLSL in general, If you want non coders to have fun using touch designer , it’s a must have.
I take it improving the modelling part , The SOPS is probably not easy thing to do, still it is some of most fun part to play with, I find. Shame its a bit limited.
Option to write GLSL shader part from a camera and things like that may help a lot the GLSL part. I’m no expert but I know the things that bug me. Hoping it helps in the updating.

I completely agree with Elburz opening comment.

+1 especially to completing the wiki with new features / parameters!

Hurray!

The wiki should even be on a new type of platform. It’s not very google search friendly.