Re: Docs confusion and missing dependency on EL9

On 2024-06-19 at 01:28:20 UTC-0400 (Wed, 19 Jun 2024 07:28:20 +0200)
Gerald Vogt <[email protected]>
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
[email protected] or [email protected]
(AKA @[email protected] and many *@billmail.scconsult.com 
addresses)
Not Currently Available For Hire