vakata/jstree — Issue #157: Documentation is Unclear
Author: blacatena
Created: 2011-12-29 16:55:25+00:00
State: open

I'm a wiz at everything who's been programming computers for 32 years, and I am struggling with jstree, only because the documentation is horrific. It looks good at first, but a million things are implied without either being spelled out, or providing easy-to-sort-out examples. This is further complicated by the older version of jstree that seems to have had major differences, so examples with that only lend more confusion.

For example, in the Types plugin you explain how to define the types, but not how to assign a type to a node (which I got working by setting an attr.rel attribute to the type).

In the JSON plugin you give two completely different examples with the same data distributed among different attributes (metadata, attr, title, id) with no rhyme, reason, or explanation.

In the UI plugin you demonstrate how to do things like the "create" operation, but that name is not the same as the create_node function, yet I can nowhere find a mapping of operation names to function names, or even a list of the valid operations.

The most obvious things one would want to do are to programmatically create and select nodes, and yet it's taken me hours to figure this all out.

I would strongly suggest:

1) A clearly defined list of all options (e.g. data elements and what they actually mean) for everything

2) Consistency among simple examples (don't load the tree in the HTML in the page itself for one plugin, then JSON in the tree creation for another, etc.). It's good to have a variety of things, but when there are too many all intermixed it's impossible for a beginner to sort out the reasons for the differences (i.e .what is relevant and what is not).

3) A "recipes" page with the things people might most often do -- but isolated to just the subject under discussion, without complicating it with other techniques at the same time