[rt-users] suggestions for improvement

[Jo Rhett]

On Dec 11, 2014, at 11:26 AM, Alex Vandiver <alexmv at bestpractical.com> wrote:
> Moving to the topic at hand: the links we provide are to the
> documentation of the module, not to the distribution page.  This is
> intentional, soas to provide the user with a longer description of the
> extension first, to let them make a more informed decision as to whether
> the extension suits their needs.

Linking to the documentation makes sense. Linking to the module docs without any clear installation instructions does not.

The concern here is that the installation process is not clear, and is *nowhere* made clear, that the extension is more than the single file. Many, many projects have extensions which are single files. Modern sysadmins install JS modules, Java plugins, browser plugins, Python modules, Ruby modules, Puppet modules, Chef cookbooks, Perl modules, etc. Even some of these configuration management packages are single files. The ones which aren’t contain clear instructions on how to install them.

Even if one is an established Perl hacker, a large majority of CPAN modules are a single .pm file. The fact that one must download the entire package, not just the singular file, is not stated anywhere. This deserves clarity.

In the current situation a person must be both an RT person and a Perl hacker to find their way through installing an extension. That’s a high bar that I don’t think helps your business. As I pointed out, I have more than 20 years of Perl experience and 10 years experience with RT and because I do things other than work on RT, and I was in the middle of a major number upgrade where everything could have changed, I made no assumption that extensions weren’t a single file. I’m a sysadmin who spent the last 16 months dealing with other software for which the extensions were a single file, and NOTHING IN YOUR DOCS TOLD ME OTHERWISE.

Every system for which a plugin is multiple files focuses on, and makes obvious, how to install the plugin. To pick a random example, when I find an extension on the Puppet forge, the largest piece of text on that very first page is "Use this command to install the latest compatible version:” which is a specific command to install that module. Beneath it in smaller text is another link "Learn about installing and upgrading modules” which covers the general case. (see links at bottom of message)

Obviously, if a confused person comes here Alex Peters’ will abuse them and talk down to them about how they’re stupid for not using CPAN to download an install the module, even though there’s no documentation for doing that either. You would at least need to pass -I /opt/rt4/lib to your CPAN invocation for this to work. So they’ll get insulted, and it still won’t work. Do you really think they’ll post again? Or will they hire someone like me to replace RT instead?

So far we have:
 1. Innocent person won’t know what to do
 2. Experienced perl hacker will probably do the wrong thing on instinct

Best Practical is a professional company who makes money selling services to people using RT.  In my experience as a consultant, I keep getting called out to sites to replace RT with “something that works”. I usually find fairly trivial problems in the installation which solve the customer’s problems, but which could not be resolved from the documentation. Experienced sysadmins follow the available instructions, things blow up — and they blame BP. Which frankly has some validity. It gives the sysadmin the impression that you can’t be bothered, and this attitude is projected onto your company and its support programs.

> I'd be open to switching existing links from
> http://bestpractical.com/rt/extensions.html to point to the metacpan
> pages, rather than the search.cpan.org ones -- I, personally, have come
> to much prefer metacpan's UI.  I'm unclear if that would address Jo's
> original confusion, however.

I believe that anything which solves the basic confusion here will be an improvement. Links as simple as the following would be a big improvement.
	[Documentation] [Download]

Something like what Puppet’s Forge, Ruby’s Supermarket, or any of these more successful extension lists do would be much much better.
	https://forge.puppetlabs.com/puppetlabs/stdlib
	http://cookbooks.opscode.com/cookbooks/mcollective
	..etc

I think the poor documentation causes BP to lose a lot of potential business, and you should consider this a priority.

Or you can continue to allow personal attacks in this support forum, and I’ll start ripping RT out everywhere instead of fixing their installations and promoting your services to them. I do a lot of RT promotion for free, at zero gain to myself. I’m not going to do that in the face of personal attacks.

-- 
Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.