Some musings on online documentation

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.

--
I'm Not Just Another Perl Hacker

Comment on Some musings on online documentation Download Code

Replies are listed 'Best First'.
Re: Some musings on online documentation by jj808 (Hermit) on Apr 15, 2005 at 15:45 UTC
Any thoughts on how to mark up external images into POD I needed to do this a while ago, and added the `O<...>` formatting code (O for Object) into pod2pdf. It's documented in perlpodextensions. JJ http://perl.jonallen.info :: http://perldoc.perl.org	[reply] [d/l]
Re^2: Some musings on online documentation by rinceWind (Monsignor) on Apr 15, 2005 at 16:24 UTC
Nice one! Looks like I'll have a go at patching Tk::Pod to implement O<...> formatting codes. -- I'm Not Just Another Perl Hacker	[reply]
Re: Some musings on online documentation by hossman (Prior) on Apr 15, 2005 at 18:14 UTC
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. I'm of the opinion that you need both ... you need authoritative documentation that says how the software is supposed to work -- if for no other reason then that it gives you a refrence point for evaluating bugs. But there is also a big advantage to having a place where your users can suply tips, tricks, caveats, and gotchas based on their own experience. Once upon a time this was handled with things like FAQs, then FAQ-O-Matic put more power in the users hands, and then Wiki's sprung up. I remember about 5 yeras ago when i got sucked into doing some PHP work with some friends. I remember loathing the language, but loving the documentation, becuase even though the PHP version of "perlfunc" wasn't as thorough as perlfunc, every function had user annotations. Since then MySql has started allowing similar anotations The problem with both of those now a days, is that there is a lot of cruft, and all people can do is "vote" for or against a single comment, not tweak it to make it better. so sometimes people wind up with an overwellming amount of comments to sift through. I think the ideal situation is online documentation, in which every section/page has an "authoritative" block of text/diagrams that is fixed in stone and only editable by your TechWriters. and a "User Additions" section that is a true wiki, where naybody can tweak/modify/add. The key is, that as new versions of your software comes out, and your tech writers write new documents, they should review what people wrote about hte old version in the wiki, and incorperate things that are still applicable into the new documentation	[reply]
Re: Some musings on online documentation by dragonchild (Archbishop) on Apr 15, 2005 at 15:18 UTC
I wouldn't think that writing a basic HTML4 (no JS) browser in Tk would be that difficult. HTML::Parser and a dispatch table should do the trick. (Note: I have exactly 0 Tk experience.) As for userdocs in general ... I have to disagree with you. The best people to write and edit user guides are power users. The best people to provide feedback on user guides are novice users. So, merge the two of them together, a la the MySQL manual. Anyone can add comments to the documentation. These can be questions, clarifications, answers to prior questions ... whatever is appropriate When a comment is added, an email is sent to the moderator(s) of that page/section/manual The moderator(s) may remove comments and edit the documentation, as appropriate The moderator(s) should include a developer, a tester, and several end users who have volunteered for this. They should meet at least once a month to go over anything that pops up. Now, in terms of the docs themselves - I would have the documentation maintained in a source control repository - my favorite is Subversion. This way, whenever an app loads, it can go ahead and update to the latest version of the docs. You can also track how the user guide has changed over time, so that the next user guide that's written can be done with "lessons learned" in mind. My wife's blog	[reply]
Re^2: Some musings on online documentation by hardburn (Abbot) on Apr 18, 2005 at 13:40 UTC
I wouldn't think that writing a basic HTML4 (no JS) browser in Tk would be that difficult. HTML4 is rather complex, and contains a lot of details that aren't useful for documentation. You almost certainly won't need frames or forms, for starters. You would probably be better off with a restricted subset of XHTML. `<p>, <b>, <i>, <img>` and maybe `<table>` and `<ul>/<ol>, <li>` are probably all you need. That will be far easier to parse than full (X)HTML. "There is no shame in being self-taught, only in not trying to learn in the first place." -- Atrus, Myst: The Book of D'ni.	[reply] [d/l] [select]
Re: Some musings on online documentation by cog (Parson) on Apr 15, 2005 at 15:36 UTC
Programmers are good at writing technical reference guides, but poor at writing user guides. Please, do not generalize. Some programmers are not so good at writing technical reference guides, and some others are very good at writing user guides. Some are bad at both, some are good at both. The best people to write user guides are users. You obviously haven't met some of the users I've met :-)	[reply]
Re: Some musings on online documentation by Courage (Parson) on Apr 17, 2005 at 15:02 UTC
Independently, I came to similar point. I didn't go that far however. I only started using wiki inside programs and generate HTML from them seamlessly. This is something like POD but for a different purpose, yet wiki has more convenient syntax, yet allow more features (e.g. tables). PS. I like your idea about ''lazy writing of documentation''.	[reply]