[Bf-python] Feedback: Examples and improvements in documentation needed

[Matt Ebb]

Hi,

Sorry about the long mail but I thought I'd make a small request for  
more examples and better organisation in the API documentation based  
on my experience yesterday at work. I needed to create an Empty at  
each vertex of a mesh, and thought it would be easy to solve with a  
simple script. I eventually got it working, but it took a fair bit of  
hunting through the 2.43 API documentation.

Looking at the first example on the Object module page gave some  
hints, but it was very had to see the relationship between the  
example Blender.Camera.New() (for which there is no corresponding  
version for empties version) and scn.objects.new() and below,  
Object.New() which is apparently deprecated. It tells me to use  
Scene.objects.new() but there's no documentation on how to use that  
there, and just taking a guess, trying:

empty = scn.objects.new('empty')    then it gave me an error.

I ended up using:

empty = Blender.Object.New('Empty', 'emp')
scn.link(emp)

which although is deprecated, was the only clear way I could find to  
figure it all out and just get the damn thing done quickly.

I had similar problems with getting the verts in a mesh, on the Mesh  
module page, it has all these nice looking examples with  
me.verts.extend and so on, but I couldn't find out what those  
me.verts etc actually are and how to use them. I ended up just  
guessing that the .verts were a container for the MVert objects and  
that I could do something like

for ve in me.verts:
	blah

but that was only because I've been subscribed to this mailing list  
and remembered the discussions on it.

Today now as I write this email and check the API reference again, I  
see links such as "MVertSeq / This object provides sequence and  
iterator access to the mesh's vertices."

I completely glossed over that yesterday since the words 'sequence  
and iterator access' mean nearly nothing to me, and it was jammed in  
with those other classes, and doesn't even have the same name! I'm  
looking for me.verts, not me.MVertSeq! I was looking for information  
on the .verts down the bottom with all the other variables that  
follow the same syntax. me.vertexColors looks like the same sort of  
thing to me as me.verts and I expected to find them together.

Also looking back through the pages, I notice now that there is a  
SceneObjects link under the Scene module which probably would have  
helped me understand what on earth the scene.objects meant, when used  
in all those examples in the Object module. Of course I didn't find  
it, it's equally hidden and with a different name like the MVertSeq  
one, and worse it's on the Scene page. I want to create an object, so  
it's reasonable to expect to find that sort of info on the Object  
page, no?

So anyway, all and all it was a pretty frustrating experience. One  
philosophy that I try to stick by in all sorts of work that I do  
related to user interaction is: "Make simple things easy and  
complicated things possible", and that wasn't the case here.

Just trying to do a really simple thing, which ended up being about 5  
lines of code once I figured it out, was quite difficult to achieve.  
I bet it wold be even harder for some Joe Schmoe who is less involved  
in Blender than I am and hasn't seen the discussions on this mailing  
list for example.

So to try and make this experience more pleasant, I would propose:
* If something is being deprecated in favour or some new approved  
way, you're trying to convince people that it's in their interests to  
do so. So if it hasn't had the heck documented out of it and there  
aren't lots of clear, explanatory examples, there's not much of an  
incentive for people to use it as opposed to the old way.
* It would be great if each example on the Module pages had a few  
lines of text not only describing what the script is doing, but also  
how, and why it is doing things a certain way, and more of this in  
the comments too rather than just describing what's happening.
* Important things like the SceneObjects etc should be linked to very  
prominently on the pages of the modules that they contain. Like on  
the Object module page: eg. in nice big letters or something "To  
access, and add to the collection of objects in your scene, use the  
_SceneObjects blahblah_". There should also be some kind of clear  
info to show that MVertSeq is me.verts - just call it Mesh.verts in  
the link for crying out loud! It's totally opaque right now and makes  
the examples hard to follow and learn more about.

Anyway, hope this helps give some idea of what it's like for a casual  
scripter who just wants to get stuff done under a deadline :)

cheers,

Matt


------------------------------------------
Matt Ebb . matt at mke3.net . http://mke3.net