[Bf-webcontent] Python API Quick Start -- slow-slog issues

[Michael Turner]

I'm new to Blender, and being more a programmer than a graphic
designer, I decided to start with this:

https://docs.blender.org/api/blender_python_api_2_67_1/info_quickstart.html

and perhaps see if it can be improved. And sure enough: lots of room
for improvement. I'd like to make these changes myself, but it's not
obvious where I'd submit documentation patches.

"Example Operator", which looked like five minutes of work, turned
into an hour. I'm finally getting some output but I'm not 100% sure
it's what's expected. Along the way, I learned the following:

"Press Ctrl+Right twice to change to the Scripting layout"

-- doesn't do anything visible. I looked around and finally noticed
"Scripting" on the top menu bar. (But it looked dimmed out, so I
didn't try it at first. See below.)

"Click the button labeled New and the confirmation pop up in order to
create a new text block"

-- there is no button labeled "New" (only in a tooltip) and there is
no confirmation pop-up.

"Press Ctrl+V to paste the code into the text panel (the upper left frame)."

-- the frame isn't necessarily in the upper left (I started with the
3D view there)

"Move your mouse into the 3D view, press spacebar for the operator
search menu, and type “Simple”."

-- spacebar doesn't give me operator search. Moreover, I had to enable
development options to get operator search

"Note The output from the main function is sent to the terminal; in
order to see this, be sure to use the terminal."

That would have been nice to know at the beginning, or at step #2:
"Start Blender" As it was, I kept wondering why output wasn't showing
up in the Python command line pane. And that Note is separated from
the instructions by this:

"See also The class members with the bl_ prefix are documented in the
API reference bpy.types.Operator."

-- which is of no obvious relevance at this point in a Quick Start
process. What a user wants to see in a Quick Start is some expected
results. Quickly. To get started. (And by the way: is there no shorter
starting example than this? How about "Hello, world"? It's
traditional, after all.

Finally: what would the expected output look like? When I finally
figured out how to see output (note: on Windows 10, use the MS-DOS
terminal, not PowerShell), I see lines like these

<bpy_struct, Object("Cube") at 0x00000250207F9598>"

My 3D View does have a light, a camera and a cube, so that matches.
But just saying that the Quick Starter is looking at object IDs could
be reassuring at that most nervous time in learning a new tool:
getting started. (I've only worked with Python a little; maybe it
would have been obvious otherwise.)

So how would I contribute copy edits to this page?

Regards,
Michael Turner
Executive Director
Project Persephone
1-25-33 Takadanobaba
Shinjuku-ku Tokyo 169-0075
Mobile: +81 (90) 5203-8682
turner at projectpersephone.org

Understand - http://www.projectpersephone.org/
Join - http://www.facebook.com/groups/ProjectPersephone/
Donate - http://www.patreon.com/ProjectPersephone
Volunteer - https://github.com/ProjectPersephone

"Love does not consist in gazing at each other, but in looking outward
together in the same direction." -- Antoine de Saint-Exupéry