Docs confusion and missing dependency on EL9

[Gerald Vogt <vo...@spamcop.net>]

Hi,

for testing I tried to install spamassassin 4.0.1 on EL9 (AlmaLinux 
9.4). I have noticed some dependencies are not mentioned on the INSTALL 
page:

I have had to install perl-ExtUtils-MakeMaker.noarch to run Makefile.PL
I have had to install perl-Archive-Tar.noarch to run sa-update.

Those two are nowhere mentioned.

It also took me a while to find the instructions how to install.

I started at https://spamassassin.apache.org/index.html

where "Click here to get started using SpamAssassin! " looked promising.

But at

https://cwiki.apache.org/confluence/display/SPAMASSASSIN/StartUsing

I have spent considerable time to look for where to download and how to 
actually install spamassassin, but eventually gave up. Only now I have 
found some instructions on the SingleUserUnixInstall page.

So I have circled back and checked the Download link from the top. There 
I can download the tar, get hints on Upgrading but still nothing on 
installation.

The Wiki and FAQ links from the top are not helpful either.

So eventually, I have found it on "Docs", pointing to the INSTALL file.

 From experience, that it not really the first place I would look.

I would think the "Get Started" page should have a link to the Download 
and INSTALL page at the beginning. Downloading and installing seem to be 
the obvious first steps to get started.

The Download page should have a link for INSTALL like it already has for 
the Upgrade.

And I would say "Where to download" and "How to install" are pretty 
common FAQs, too.

I hope this helps.

Thanks,

Gerald

Re: Docs confusion and missing dependency on EL9

[Bill Cole <sa...@billmail.scconsult.com>]

On 2024-06-19 at 01:28:20 UTC-0400 (Wed, 19 Jun 2024 07:28:20 +0200)
Gerald Vogt <vo...@spamcop.net>
is rumored to have said:

> Hi,
>
> for testing I tried to install spamassassin 4.0.1 on EL9 (AlmaLinux 
> 9.4). I have noticed some dependencies are not mentioned on the 
> INSTALL page:
>
> I have had to install perl-ExtUtils-MakeMaker.noarch to run 
> Makefile.PL

That module has been a part of the Perl "core" in all versions of Perl 
5.

> I have had to install perl-Archive-Tar.noarch to run sa-update.

Archive::Tar has been in the core since Perl v5.9.3

> Those two are nowhere mentioned.

A standard Perl installation of any version we support will have both of 
those.

RedHat, for reasons of their own, splits the Perl core into many 
packages. To get the standard core on any EL-based system, install the 
"perl" package.

> It also took me a while to find the instructions how to install.
>
> I started at https://spamassassin.apache.org/index.html
>
> where "Click here to get started using SpamAssassin! " looked 
> promising.
>
> But at
>
> https://cwiki.apache.org/confluence/display/SPAMASSASSIN/StartUsing
>
> I have spent considerable time to look for where to download and how 
> to actually install spamassassin, but eventually gave up. Only now I 
> have found some instructions on the SingleUserUnixInstall page.
>
> So I have circled back and checked the Download link from the top. 
> There I can download the tar, get hints on Upgrading but still nothing 
> on installation.

There is a link at the top of the homepage to "Download" and in the 
tarball on the download page there's a document named "INSTALL"

The overwhelming majority of users who install SA do so using their 
system's packaged version or CPAN.


> The Wiki and FAQ links from the top are not helpful either.
>
> So eventually, I have found it on "Docs", pointing to the INSTALL 
> file.
>
> From experience, that it not really the first place I would look.

That certainly varies by individual. I definitely look to the 
documentation for information on how to install software.

> I would think the "Get Started" page should have a link to the 
> Download and INSTALL page at the beginning. Downloading and installing 
> seem to be the obvious first steps to get started.

I agree. The whole logical structure of the website needs a more 
rigorous review.


> The Download page should have a link for INSTALL like it already has 
> for the Upgrade.
>
> And I would say "Where to download" and "How to install" are pretty 
> common FAQs, too.

Indeed.

-- 
Bill Cole
bill@scconsult.com or billcole@apache.org
(AKA @grumpybozo@toad.social and many *@billmail.scconsult.com 
addresses)
Not Currently Available For Hire