Re: [orca-list] Help write Orca docs

[Andre Nuno Soares <ans meo pt>]

Hi Willie,

On Thu, 2009-10-22 at 08:43 -0400, Willie Walker wrote:
> > 1) Does it make sense to have 2 separate documents?
>
> I think it is important to have both a tutorial and a reference aspect. 
>   Whether the document sources need to be completely separate is to be 
> determined -- I *think* mallard might provide some means for keeping 
> things as individual topics in individual files, but allow for some 
> sort of separate meta threading to provide different paths through the 
> files.  If this were possible, we could help eliminate one of the 
> biggest issues with maintaining separate documents: duplicate 
> information.  That is, it's easy to copy/paste information between 
> documents when writing them the first time, but making sure you keep 
> the copied information in sync while updating the document becomes an 
> arduous task.

You're right. I was being too "linear".
 Mallard seems particularly suited for creating different "graphs" from
a set of nodes/topics, so that it is very simple to have a Firefox cheat
sheet as a part of the Firefox tutorial  _and_ the Orca cheat sheetss.
> > 2) Should the Introductory Guide cover configurations and/or shortcuts
> > that are independent of Orca, but very useful to a VI user?
> > Examples:CTRL+L jumps to the Location barin Firefox, F9 sends and
> > receives mail for all accounts in Evolution, CTRL+S saves the current
> > document in Gedit /among others)...
>
> I think including these is a good thing (as would hints such as 
> pressing F7 to enable caret navigation mode).  My thinking is that some 
> of our audience will be people coming from different environments 
> (e.g., Windows) and they will want to know "what's my e-mail client?", 
> "what's my chat client?", "what's my simple text editor?", "what's my 
> document/office client?", and "how do I use them?"

I totally agree. IMHO, this is more important than "In JAWS/WindowsEyes
you did it like this, inOrca it's like this", because the big
differences are in the aplications and the OS.
> > 3) Should the 'Help' button in Orca main window point to the 'cheat
> > sheets' in yelp, or to the Guide?
>
> In general, I think the convention is to point to the guide.  For the 
> 'cheat sheet' information, would the keyboard bindings tab of the 
> preferences UI be enough of a quick reference?

That's what I still do today :-) 
Both for JAWS and Orca, that's the help information I access the most.
Maybe place a link in the front page of the guide to the cheat sheets?
> > In the mean time, I volunteer for the Evolution and Firefox tutorials.
>
> Since you seem to be doing a really really good job so far on the high 
> level organization, would you  like to keep running with the overall 
> docs?

Sure, I'll be glad to help where I can. I'll try to fire the "first
shot" with the Evolution and Firefox tutorials, as I am using this to
learn Mallard, but it shouldn't take much more time.



AndrÃ