Parrot's Documentation set

[Moritz Lenz]

Hi,

On 10/26/2011 05:56 PM, Alvis Yardley wrote:
> (2) simply has an opinion
> about the present condition of Parrot documentation,[2] 

my experience is that finding the documentation for something is quite
hard, even if it exists.

For example if I tell you that there is a way to take a number to the
power of e in Parrot, where would you look?

With a bit of experience, you'd probably know that it will likely be a
PMC or an opcode, so two options already. If you think it's an opcode,
you'll probably end up at
http://docs.parrot.org/parrot/latest/html/ops.html. So, what could it
be? a core op, maybe? nope. A math op? nope. Wait, there's a *second*
link to math ops, this time as dynops. How would I know if I should look
into the math ops or the math dynops? no idea. Anyway, it's not there
either.

Maybe it falls into the category "Obscure Mathematical Opcodes"? Nope.
"Transcendental Opcodes" it is, after just a few wrong guesses.


Another example: docs/compiler_faq.pod contains the line

    cfg = interp[.IGLOBALS_CONFIG_HASH]

I still have no clue if the IGLOBALS_* constants are documented
anywhere, and if yes, where I'd find that documentation.


I hope those two examples demonstrate the problems I have with finding
documentation (though the first example may also reflect a suboptimal
factoring of the opcodes themselves -- do we really need so many places
to stuff math related opcodes into?).

I don't know what a good solution would be, just some rough ideas:
 * a search function for the docs
 * an overview document which lists all headings from all docs (and
which I could search with the in-page search feature of my browser)
 * maybe a better overall structure could be found, though I have no
idea how that would look like.

Cheers,
Moritz