Re: Documentation for POE?

[Azhrarn]

Documentation has been an admitted problem, and they are trying to form a scheme to keep things coherent. There is a ton of documentation in the fairly dense POE modules themselves, and Dngor is working on consolidating it into more readable forms.

Good places to start:
Beginners Guide
Dennis Taylor's Introductory Article (Raw POD, but I found it a good read) (EDIT: Woops, seems to be the same article as Mr Person's perl.com link. :) - Not sure if there are revisions in the POD or not)
POE FAQ
POE Cookbook
Evolution of a POE Server (A GREAT guided tour through designing a POE application from the ground up)

Out of the Main POE docs, POE::Session is probably the most important to understand, closely followed by POE::Kernel. As you can get by with just understanding the constants the Kernel exports at first.

I've read through the majority of the POE docs many many times over the past few months as I dabble in various projects, and still keep coming across more little things. Also, don't be afraid to just make your own page on the wiki and post questions there, or even on an existing page like the FAQ. It lets the friendly devs over there know what parts confuse people the most, and someone usually sees your question fairly quickly and will be happy to help you understand it.

[DrHyde]

Trouble is, having a ton of documentation is not really useful if there's not enough introductory stuff. POE suffers from this. The way people use documentation, at least when starting out, is they want to ask "I have problem X, how do I solve it". The POE docs don't help here, they're just a reference - at least that was the case last time I looked. But a reference is only useful once you know what you're doing.

Last time I whined about this, Rocco said that he knew it was a problem and he'd be happy to accept any documentation I could write. Unfortunately there's a bootstrapping problem there - without having sufficient documentation I couldn't learn the product in any reasonable time scale and so couldn't write the documentation.

exim suffers from the same problem. I learnt exim not from the docs but by taking someone elses config file and hacking it until it Did The Right Thing. I tried to learn POE the same way - taking the test suite and trying to turn it into my application, but POE's just a wee bit too complicated for me to learn it that way ;-)