After reviewing the traitlets refactor #55, I think that an essential part of this is to have a standardized way to list specifically the attrs and params in the docstrings for Nodes (in addition to the normal Attributes section).
I don't know Sphinx well, but we could add custom sections for attrs and params, right? It would be cool if it could Sphinx introspect for attr and param tags, but that seems like to much to ask for.
It think these sections would include all tagged attrs and params from parent Nodes, so that anyone just trying to use a particular Node can quickly find the attrs they can set and the params they can evaluate with. I think that would address the issues @mlshapiro brought up, while more advanced users who are writing custom Nodes would be more familiar using traitlets and with finding documentation for inherited class attributes.
attrs are set at Node instantiation and then cannot be changed. You can set defaults in the class definition.
params are passed in when executing the node (so you can execute a node multiple times with different params). You can set defaults in the class definition and at class instantiation.