State of the Documentation

The Perl 5 tutorial for freiesMagazin (the first and hardest part) is complete and I'm very happy about it (read it in the next month issue). It was a great teamwork and all who read it so far, like it very much. The result will reside in the wiki of perlcommunity.de (link later when arrived there), so it can be further expanded/improved/updated and can help a lot people more. Because its the most visited Perl forum in German and thanks to tinita++ we have there banners that link to different important pages in the wiki which gets 20 times more visited than the others.

You maybe say OMG no no no please send me to detroit but not another Perl tutorial. So take you lists of tuts you know and scrap all that are not German, all that are not up to date with Perl 5.14, all you have to pay for and all that don't take full advantage of HTML and I wonder if there is anything left.

I spent some years in the madcage of the wikipedia and learned some things. Not only how to write in a certain style and how sort and categorize things but also how people read and search for the information bits they need. This I will not only bring to the Perl 6 world in form of the Perl 6 Tablets which even got the support of the TPF. I want it also bring it to the Perl 5 world in form of a an Application that I want call docular, that will arrive at CPAN as App::Gui::Docular. I started and announced it a while ago and it layed dormant but its not dead. I strongly believe that there will be a great benefit to have doc content you can approach as hypertext, with bookmarks and parallel views, put bits of text aside you need and copy the hole together and go into your editor. That are only a few things possible. Part of that became normal browsing behaviour anyway. But there is a lot more improvable.

I also seen the shiny class browsers in the ruby world, in their version of cpan. Except they are not really useful when they have autogenerated stubs that are not really helpful. Thatswhy I bet more on handcrafted content, that contain examples. More work it is, yes, but maybe the best documentation for larger modules. I will try it for wx and maybe later we get something for Perl 6 too. Because it will be saved in a YAML or JSON format other can easily contribute docs for their project. And my dream is that every important Module on CPAN delivers such a file.

Yes its some work and currently im busy with other things. Also my grant manager Tom Hukins doesn't got a lot cookies lately. But I would like to read your ideas about that idea. So we can create a better version of docular which is for me anyway a part of my effort to write the WxPerlBook.

Thank you very much.

Leave a comment

About lichtkind

user-pic Kephra, Articles, Books, Perl, Programming