Re: [orca-list] Some of my thoughts about what has been difficult for getting into orca development and orca scripting

[Joanmarie Diggs <joanmarie diggs gmail com>]

Hey Michael.

Thanks for raising these issues. We need to hear exactly these sorts of
things.

> I did try some time 
> ago to get involved more technically with orca but got a little 
> overwhelmed with it and where to really get going.

Yeah, it can indeed be hard to sort things out initially. There are a
few of approaches you might wish to try:

1. More advanced/in-depth bug triage.

Follow the steps outlined here:
http://live.gnome.org/Orca/HowCanIHelp#Help_Triage_Problems

In particular, focus on step 4, namely:

        Compare the two debug.outs. They should be awfully similar
        because the only thing that's different is your favorite app,
        and you've taken the time to find the exact version of that app
        where things changed. So find out what happened: Look for events
        that are missing. Look for new events. Etc.

When I was first getting started, I read a lot of debug.outs. And my
eyes crossed. And I thought it was all gibberish. But eventually things
started making sense and I was able to see the patterns that existed
between my actions (in the form of keyevents) and the resulting
accessible events that were emitted, and then how Orca responded as a
result of those events. That's half the battle in script writing.
Actually, it's more like three quarters of the battle.

2. Pick an existing script and pepper each method with calls to
speech.speak() so that you can have Orca give you a running narrative of
where it happens to be and what it happens to be doing as it's doing it
without your having to wade through a full debug.out. And, yeah, this
approach sounds silly, but early on I did this quite a bit and it helped
me figure out what the heck was going on as it was going on.

3. Think of a *small* task/change you'd like to see in Orca. For
instance, Steve wants Orca to announce when overwrite mode gets toggled
in Gedit. If you start small, rather than try to write an entire script,
I think you'll have more success.

Regardless of the approach(es) you choose, ask on the list. And when you
do ask, be very specific and bite-sized in your questions. For instance:

Bad: What the heck is all this stuff in debug.out?

Good: I pressed this key, and as a result I saw the following three
events in my debug.out: <quote only the immediate/resulting lines here>.
But I'm not sure how to interpret what x, y, and z in the above lines
mean.

Bad: I want to write a script for application foo. How?

Good: I want to cause Orca to announce every time I change my text
alignment in application foo. When I do this, I see the following events
emitted by foo: <quote event output from debug.out or Accerciser here>.
How can I use these events to cause Orca to announce the alignment
change.

Keeping things bite-sized should not only help all of us (askers and
responders) from getting overwhelmed by really large/in-depth issues,
but it should also make it easier for interested users to follow along
and become more familiar with Orca development. With any luck, it might
even result in sample problems/tasks on the nature of scripting which
can more or less be copied and pasted into our (not-yet-written) guide
for users on how to script.

> The thing is there 
> seems to be a bit of this step from reading docs on python and at-spi, 
> etc (thanks Willie for those useful links, they did help), to actually 
> working with the orca code. 

To be perfectly honest, I did all three of the approaches I mentioned
earlier in this message before I did any serious doc reading. That
doesn't mean you don't need to read the docs, or that the knowledge
therein isn't critical to making large, significant contributions to
Orca. It just means that, in my personal opinion, all of that
information is largely theoretical until you actually get a feel for
what on earth is taking place. Were I you (and as a reminder, I was you
a few years ago), I'd roll up my sleeves and get my hands dirty first.
Then read the docs.

> An example of what I got stuck with was if 
> looking through the bugs in bugzilla, which may be easy to solve and 
> which may be a bit too hard for someone just picking up orca code, is 
> there any way we could be pointed to that low hanging fruit to get 
> started?

Funny you should mention that. <smile> My goal for today through Monday
is to go through every last one of our bugs, find out what is still
blocked, what needs to be verified, what ain't gonna get fixed any time
soon, what can be fixed now -- and potentially by whom, etc., etc. 

What I was thinking of doing with respect to low-hanging fruit is using
those bugs/RFE's as a vehicle to address the sorts of issues you raise
here. Until I see what all we have on the fruit tree, it's hard to say
what the best approach might be, but a couple of possible scenarios:

1. Members from the community take on the low-hanging fruit and we all
help each other out, asking questions here and/or on bugzilla.

2. The fixer (me or someone else) takes the time to write out in detail
exactly how he/she went about identifying the issue, arriving at the
solution, and implementing it, and then shares that here and on the wiki
(i.e. as a tutorial).

> What I mean by this is, I understand the orca wiki 
> (http://live.gnome.org/Orca) as the main place to start looking, I don't 
> think there is a link for the orca manual there.

Feel free to add such a link. It's a community wiki after all. <smile>

Thanks again for your thoughts and ideas. Keep 'em coming!
--joanie