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 _______________________________________________ http://lists.parrot.org/mailman/listinfo/parrot-dev
