[rt-users] Documentation for installing extensions

[Jo Rhett]

On 12/12/2014 02:39 AM, Jo Rhett wrote:
>> Linking to the documentation makes sense. Linking to the module docs
>> without any clear installation instructions does not.

On Dec 12, 2014, at 10:06 AM, Alex Vandiver <alexmv at bestpractical.com> wrote:
> Picking a commonly-used module, RT::Extension::SLA, and looking at the
> documentation we link to:
> 
> http://search.cpan.org/~alexmv/RT-Extension-SLA-1.03/lib/RT/Extension/SLA.pm#INSTALLATION
> 
> It contains an "INSTALLING" section which details the steps necessary to
> install the module.  I believe that all, or nearly all, of the modules
> that Best Practical places on CPAN have a similar section.

I’m not sure where you are looking. I’m at https://www.bestpractical.com/rt/extensions.html and it links to https://metacpan.org/pod/RT::Extension::SLA without #INSTALLATION.

None of the modules I looked at or included in my original report linked to an INSTALLATION section. In a section below I go through the first six modules provided by BP, and not a single one of them links to installation instructions, and most of them don’t have that section at all.

It seems you’ve updated this to link to MetaCPAN now. That does look better, but I’m not sure that the “Source Code” link is truly an improvement, for a reason I’ll describe in my next reply below (read down)

> Can you point me at documentation which suggests downloading one file
> from CPAN and putting it in place manually?  Perl's own core
> documentation (http://perldoc.perl.org/perlmodinstall.html ) suggests:

And this is the core issue that both you and Alex Peters seem to be hung up on, which I keep addressing over and over again but it’s not getting through. Let me try another way.

Puppet is written in Ruby. Puppet modules are written in Ruby and Puppet Ruby-DSL. If you want to write a really good Puppet module, you need to be a Ruby coder.

HOWEVER, tens if not hundreds of thousands of people use Puppet and install Puppet modules (e.g. extensions) without knowing how to code in Ruby, without having read the Ruby documentation, and without being able to write a single line of Ruby code. They are able to install and use Puppet extensions, without ever learning Ruby.

I would think that this would be a desirable situation for RT. Nearly nobody is hiring these days for Perl knowledge, and that every company I’ve worked at in the last 10 years has been replacing and removing Perl in favor of Python or Ruby. There are numerous places who have refused to consider RT simply because they don’t support Perl. Given this environment today, there is significant advantage for Best Practical to lower that barrier to entry, and make RT work without Perl competency.

Obviously there are numerous places that BP would need to change the installation process to make this work better, however this is clearly one of those places. It would be an improvement.

> Can you point me at documentation which suggests downloading one file from CPAN and putting it in place manually?

You linked directly to the singular file. That is the appropriate approach for many, many systems where the plugin is a single file. Remember that there are no sysadmins who know nothing beyond RT and never use any systems beyond RT.

> Perl's own coredocumentation (http://perldoc.perl.org/perlmodinstall.html ) suggests:

...
> These are thus the steps which RT extensions mirror in their installation.

I have used numerous self-contained Perl applications which would not work properly if you simply CPANed the module in. I’ve worked in two companies who exclusively used their own library paths to avoid the breakage associated with random CPAN upgrades. No, it is not “obvious” that simply using CPAN or any other “standard perl thing” to install the package would be appropriate.

So let’s start at the top of extensions try to follow the clear process for each one. For this I’m going to exclusively use modules provided by Best Practical.

https://metacpan.org/pod/RT::Extension::ActivityReports#INSTALLATION
	— does not link to installation as you suggested above
	— forgets to mention that you need "-I /opt/rt4/lib” so fails on my fresh 4.2.9 installation

https://metacpan.org/pod/RT::Extension::ActivityReports::Billing
	— error, not found

https://metacpan.org/pod/RT::Extension::AddAdminCcsOnQueueChange
	— no installation instructions

https://metacpan.org/pod/RT::Extension::AttributeWalker
	— no installation instructions

https://metacpan.org/pod/RT::Authen::Bitcard
	— no installation instructions

https://metacpan.org/pod/RT::Authen::ExternalAuth#INSTALLATION
	— does not link to installation as you suggested above
	— forgets to mention that you need "-I /opt/rt4/lib” so fails on my fresh 4.2.9 installation

Do I really need to keep going?

In short, yes a Perl hacker can figure this out. Is your target audience ONLY perl hackers? This is the key point I’m trying to get through.  If you only want to sell RT and its services to Perl hackers, then feel free to ignore my advice.

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