...and i am starting to understand why. turns out that doing a tutorial with beginning programmers (first year computer science students) is really helpful.

these students have no problem to understand the syntax, they where happily working with the examples and understanding how to apply them to solve their problems, but once you point them to the module reference they become lost.

here is what i experienced today: .... students: we'd like to do this interface with 3d graphics. me: ok, lets take a look at GLUE, which should make this easy.

we find GLUE.init() and after explaining the use of the backend, figuring out that the default is fullscreen, how to fix that, etc, we wonder what's next.

me: lets try to draw something. here draw_box() looks promising:

void GLUE.draw_box(float x0, float y0, float x1, float y1, array(Image.Color.Color)|Image.Color.Color c, void|array(float)|float a)

students: what is this Image.Color.Color? me: lets take a look: well it's a color object. to see how to use it, we look at the create function http://pike.ida.liu.se/generated/manual/modref/ex/predef_3A_3A/Image/Color/C... me: see, it takes 3 arguments, for each of the parts of a color. students diligently type: Image.Color.Color.create(255,255,255);

me: oh, wait, (explaining the use of create) Image.Color.Color(255,255,255); Compiler Error: 1:Too many arguments to clone call. Compiler Error: 1:Expected: function( : object(is 200)) Compiler Error: 1:Got : function(int(255..255), int(255..255), int(255..255) : void | mixed)

me: say what??? this is wierd!

being creative, i try looking at Image.Color, find the description we were looking for, and use Image.Color("red"); ....

can anyone see where the problem is? if you are new to pike, you lack the creativity needed to figure out how the documentation is to be interpreted.

at the pike conference someone mentioned at one point that it would be useful to hide the create() function, and display it instead more prominently. actually pretty much like in Image.Color.

but that is just one thing. in this example: the color type is referenced as Image.Color.Color and this reference was not really helpful in determining what you really need to do to obtain such an Image.Color.Color object.

why is that?

details like these are spread throughout the reference, i don't know if there are any more misleading like this one, but i now understand much better why people still complain about the documentation.

beginning programmers simply get lost. for them, these issues are not obvious.

so there is still a lot of work to do. it's time we get that bounty program rolling. (more on that soon in an extra message)

greetings, martin.