I think it needs to be done and is long overdue.
The SideFX Houdini node descriptions keep being mentioned and they do have a very good format. I think we should aim for something along those lines.
One issue is that colour nodes are much easier to show how they work than scalar or vector (see my illustrations above) but I think that is surmountable.
I keep coming back to my point about gaining a META understanding of how the nodes work. As shown above when we learn that the
ADD_COLOUR node is the same as (and an internal component of) the
Add colour element of a merge node we learn very much more than when we simply describe what the ADD_COLOUR does.
I think this needs to be reinforced across the node descriptions. Show how blue nodes are the building blocks of the red nodes at every opportunity. Integrating new knowledge with old knowledge is the key to successful learning.
I also believe that a foundation "chapter" needs to be laid out talking about:
1: the three types of node input/output (Colour, Scalar, Vector), what they are and how they are used
2: the two types of space (texture space and world space).
(please correct me on this )3: the difference between linear colour space and (photoshops) Gamma colour space.