Re: [orca-list] Is any Technical documentation or technical reference Document available for Orca3.X ?

[Jason White <jason jasonjgw net>]

Alex Midence <alex midence gmail com> wrote:
> I wonder if anyone has thought to use something like Doxygen to autogenerate
> some rough-hewn technical documentation which can then be embellished up to
> spec as it were.  Would this even be a feasible idea?  I've seen several
> inquiries throughout the last couple of years I've been on this list asking
> for just exactly this sort of technical documentation.  Trouble is, it's a
> tedious, thankless job to produce and keep up with.  It's literally
> deserving of its own maintainer so that it stays current.  I imagine finding
> someone willing to maintain the technical docs wouldn't be so hard if only
> the initial writing were completed before such a person took up the
> maintenance task.  

There are surely tools that can generate documentation from Python
documentation strings. This kind of documentation is most often written when
there's an API offered to applications, which isn't the case for Orca.

I'm wondering whether an architectural overview, rather than
function-by-function documentation, is more what people with Python expertise
coming to Orca need. Those without good Python skills aren't going to be able
to contribute much anyway, so our audience really consists of those who
already know the language well enough to get started looking at Orca.

More urgent, I think, is documentation for application developers to help them
support ATK. If the ATK/AT-SPI infrastructure were better documented and
explained, at least there would be references that application developers
could rely on.

> I find myself wishing I could do something towards this
> but I lack the necessary expertise to do a proper job of it and don't want
> to make a hash of things by hamfisting it.  Any thoughts by anyone?  Is my
> assessment of things even correct?

Partially. I think the underlying problem is that this entire area has been
lacking in resources for years now, new contributors are highly desirable, and
the work required to make it easier for them has never been done, but ought to
be done. For example, if more people were to fix accessibility bugs in
libraries and applications, and push patches upstream, the quality of support
would improve enormously. Many of the problems are outside of Orca itself and
outside of the ATK/AT-SPI code. Currently, the problem is that bug reports are
submitted to the relevant library or application, then everybody waits for
someone who is working on that software to identify the cause of the problem
and fix it. If more bug reports had patches included, progress would be a lot
faster, in my opinion.