I'm currently going through an exercise adding online help to some Tk applications. I've discovered that Tk::Pod::Text gives a nice hook to the POD. Here's an example:

#!/usr/local/bin/perl

use strict;
use warnings;

use Tk;
use Tk::Pod::Text;

our $VERSION = 0.01;

my $mainw = MainWindow->new;
$mainw->configure(-menu => my $menubar = $mainw->Menu);

$menubar->cascade(-label => "~Help",
                -tearoff => 0,
                -menuitems =>[
                        [ command => '~Documentation',
                         -command => \&pod_window ],
                        [ command => '~About',
                         -command => \&about_window ]] );
# ...

sub about_window {

    $mainw->messageBox(
                -title => 'About',
                -icon => 'info',
                -message => "Version $VERSION",
                -type => 'Ok' );
}

sub pod_window {
    my $hw = $mainw->Toplevel;

    $hw->Button( -text => 'Close',
                 -command => [$hw => 'destroy']
        )->pack( -side => 'bottom' );

    $hw->Scrolled( 'PodText', -file => $0, -scrollbars => 'e'
        )->pack( -side => 'top',
                 -expand => 1,
                 -fill => 'both' );
}
[download]

I've had some feedback from a principal user. What he really would like to see inside the documentation, is some screen shots. However, I have persuaded him that this is non-trivial, and he is living with just having the text for now.

I was thinking that perhaps if I had produced an HTML document in the first place, adding images is trivial. But this would involve launching a browser from the application, and seems messy, in that the deliverable is now not all in one place.

Any thoughts on how to mark up external images into POD, and how to hook this into a Tk text box would be appreciated. Or, if there's a full blown HTML browser available in Tk I would be most interested.

This has brought to mind an experiment with online documentation at a previous place of work:

• Programmers are good at writing technical reference guides, but poor at writing user guides.
• The best people to write user guides are users.
• Allowing write access to the documentation yields better documentation and leads to happy users :).

This experience was 5 years ago. Sadly, this idea was killed by some politics - interference from the marketing department and the technical documentation team feeling that we were trying to put them out of a job. In the mean time, wiki technology and has become much more popular and widespread.

So, I'm wondering if anybody out there is providing help texts as wikis. This is a lazy way of building documentation, and certainly one way of building a community of application users, especially if the wiki is central and web based. You might need some partitioning to allow individual clients to have their own specific areas in the wiki, or a subwiki delivered with the application, hosted on their own intranet.