@JakHussain @theor-unity @willgoldstone et al
The progress on Visual Scripting Graph and active, iterative communication with the community has been really exceptional so I want to acknowledge that and not lessen the much deserved accolades here. And I’m not complaining of the fact that there is early documentation so this is not a direct criticism to the visual scripting team or anyone applauding documentation.
I just want to take the opportunity to outline a reminder to all following these developments that a ream of documentation is not necessarily something to strive towards for experimental or alpha software that is subject to change and render those docs inaccurate or in need of constant edits and re-writes. Even with a dedicated team writing and maintaining docs, there is close and constant communication needed with the developers to keep everything in sync… which in practice can be very challenging to maintain. Especially for software meant to be visually intuitive as a core reason for it to exist… Too much focus on documentation, or too early, instead of core functionality / usability, reliability can be (and has been) a detriment in many software projects.
If anything, this is speaking to anyone that’s ever been expectant of exhaustive documentation for software that should / could have an intuitive UI/UX instead. Visual programming tools, (directed node graph, block, etc) fall at an interesting intersection where they definitely need some technical documentation / reference… but their visual elements need not be documented like a code framework or API, or it may miss valuable opportunities in usability because “it’s in the documentation” or the old saying of “RTFM” as it’s known :). So, there may be a schism in how people view this, and… both views are correct, just slanted towards different use cases of visual programming tools.
Shader Graph as an example has had some of these issues where the documentation / reference describes certain functionality of nodes for swizzling / splitting / joining that 1. should be for 9/10 cases self explanatory / discoverable and not need documentation… 2. has features documented that to my knowledge never worked properly (dynamic component output) and the Shader Graph team has (indirectly through support channels) refused to address the issue or update the documentation to reflect the actual functionality, noting there is an (un-intuitive) workaround to the dynamic vector output size bug, and noting will be a major redesign & refactor someday soon anyway that will address this with a different approach. That said, it’s been leaving a bad taste in my mouth and anyone learning or using Shader Graph that’s come across these usability issues ever since it was declared production ready. Then there are other sections of the Shader Graph documentation like the master node reference that has been incomplete and out of date for a year at least and should just be removed if they won’t be maintained. Again… why we even need exhaustive documentation for a visual tool that should document itself in its own UI is beyond me. Old standards and expectations die hard I guess. I don’t mean to single anyone involved with Shader Graph team out anyway and I know they have plans to address all this. Unity strongly acknowledged on the 2020 roadmap talk that the development pace the last few years was overly rushed / crunched and I presume this was a significant factor to projects like this falling into default minimum viable product territory as such.
This is in contrast to the Visual Effect Graph team which has focused on usability, intuitive UI like vector component swizzling / split / join that is built into every operator node with a simple and self-explanatory expand/collapse widget. It saves the user from (in Shader Graph’s case) needing to peruse out of date documentation of a Swizzle node to inaccurately describe its already stilted design usability using drop down menus. And then find a tutorial / example to find out about the Split and Join nodes that seem to be the way that the majority of Shader Graphs actually swizzle vectors. Interestingly, There was actually a previous version of the Visual Effect Graph documentation that contained an attempt at an exhaustive node reference which was later removed and instead replaced with cursor hover tool-tips in the graph UI on the nodes themselves. Leaving the Visual Effect Graph docs to focus mostly on the philosophy and visual language to onboard users into an intuitive flow with the UI/UX… so that they can hopefully not need to return to the documentation again… (unless it’s for say, about writing code for a customization API.) While not a perfect or complete solution, this pivot was a bold but wise move that is inline with visual programming paradigms and modern UI/UX. (To be fair, I’m going to guess the Visual Effect Graph team probably had less pressure and other packages depending on their results than the Shader Graph team did, which may have let them explore and hone Visual Effect Graph in from a usability point of view like this.)
As such, I hope and expect that all visual programming packages underway at Unity continue in this direction, lessons learned. The expectations surrounding their documentation takes a significant backseat from the developers and the users perspective, with a firm focus on the product’s functionality and usability. At least until the package is significantly mature or at least production ready, etc.
I might be preaching to the choir here as they say, I have shared similar sentiments on other threads before. Anyway, I’m sure someone may benefit from these ideas even if it’s redundant in the context of Visual Scripting Graph’s development goals, so, thanks for hearing me out.
