Login | Register 
FEATURES
APPLICATIONS
DOWNLOADS
EDUCATION
BLOG
WIKI
FORUM
STORE

Complete Operator Docs + Snippets

Send us your requests for enhancements (RFEs)

Complete Operator Docs + Snippets

Postby elburz » Thu Jun 13, 2019 3:41 pm

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.
--
Elburz Sorkhabi
Creative + Technology
nVoid Art-Tech Limited
http://nvoid.com
elburz
 
Posts: 2016
Joined: Fri Jun 01, 2012 6:55 pm
Location: Toronto, Canada

Re: Complete Operator Docs + Snippets

Postby jpyepez » Thu Jun 13, 2019 7:17 pm

Bump! Documentation and snippets are critical at this point.
jpyepez
 
Posts: 7
Joined: Wed May 03, 2017 5:28 am

Re: Complete Operator Docs + Snippets

Postby doctorhandshake » Sun Jun 16, 2019 11:44 am

+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.
Noah Norman
http://hardwork.party

codename: massapequa
User avatar
doctorhandshake
 
Posts: 139
Joined: Wed Aug 17, 2011 6:31 pm
Location: Brooklyn, NY

Re: Complete Operator Docs + Snippets

Postby jmt4zj » Sun Jun 16, 2019 8:29 pm

+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.
Jonathan Thompson
@pointshader
http://pointshader.com
User avatar
jmt4zj
 
Posts: 160
Joined: Mon Nov 01, 2010 3:15 am
Location: NYC

Re: Complete Operator Docs + Snippets

Postby delray » Tue Jun 18, 2019 1:13 pm

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!
User avatar
delray
 
Posts: 149
Joined: Thu Jun 30, 2011 9:38 am
Location: Montreal, QC

Re: Complete Operator Docs + Snippets

Postby malcolm » Thu Jun 20, 2019 2:43 pm

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.
User avatar
malcolm
Staff
 
Posts: 4396
Joined: Tue Nov 13, 2007 1:11 am

Re: Complete Operator Docs + Snippets

Postby elburz » Thu Jun 20, 2019 4:51 pm

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.
--
Elburz Sorkhabi
Creative + Technology
nVoid Art-Tech Limited
http://nvoid.com
elburz
 
Posts: 2016
Joined: Fri Jun 01, 2012 6:55 pm
Location: Toronto, Canada

Re: Complete Operator Docs + Snippets

Postby greenpattern » Fri Jun 21, 2019 5:22 am

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.
User avatar
greenpattern
 
Posts: 231
Joined: Tue Dec 01, 2015 3:05 pm
Location: Edinburgh Scotland, but I'm french

Re: Complete Operator Docs + Snippets

Postby FaustoB » Mon Jun 24, 2019 6:52 am

I completely agree with Elburz opening comment.
FaustoB
 
Posts: 64
Joined: Mon Jan 08, 2018 8:33 am
Location: Sydney, NSW

Re: Complete Operator Docs + Snippets

Postby vinz99 » Fri Jul 26, 2019 3:01 pm

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

malcolm wrote: As a first step we plan to make a company wide effect to fill in all of the missing documentation in the wiki ASAP.


Hurray!
vinz99
 
Posts: 374
Joined: Wed Apr 15, 2009 10:34 am

Next

Return to Wishlist and RFEs

Who is online

Users browsing this forum: No registered users and 5 guests