Re: [orca-list] Help write Orca docs

[Willie Walker <William Walker Sun COM>]

Andre:

> Following your (brave?) invitation for us to add our thoughts on the
> subject, I reorganized the page and tried to start structring the new
> documentation.

You are doing awesome!  Many thanks for jumping on this.

> 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.

> 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?"

> 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?

> 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?

Thanks so much!

Will