Re: [orca-list] Help write Orca docs

[Andre Nuno Soares <ans meo pt>]

Hello Willie/all,

On Thu, 2009-10-15 at 11:18 -0400, Willie Walker wrote:
> I created http://live.gnome.org/Orca/DocRewrite as a means to track our 
> thoughts on the Orca documentation rewrite.

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.

I think we need 2 manuals, an introductory Guide to "Computing with
Orca",that is, using orca in gnome/firefox/Evolution/etc  and a
Reference Manual, where besides the 'cheat sheets' we'd have the more
advanced sections, like customizations, different sound systems, etc.

This is very similar to what you had written there, but since a Wiki
isn't a good place to exchange ideas, I'd like to put to the list:

1) Does it make sense to have 2 separate documents?

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

3) Should the 'Help' button in Orca main window point to the 'cheat
sheets' in yelp, or to the Guide?

> I believe keeping the documentation in some sort of XML format (e.g., 
> DocBook or Mallard) will allow us to generate the documentation in many 
> different forms: one big HTML file, a 'chunked' HTML file, PDF, online 
> help, maybe DAISY, etc.

I didn't find much on Mallard, especially on tools to help writing. Can
anyone help with this?


In the mean time, I volunteer for the Evolution and Firefox tutorials.


Andre