Is it still worth adding installation instructions to a distribution?
I have decided to write a successor to Pod::Readme that works as a Dist::Zilla plugin that plays well with Pod::Weaver.
The idea for Pod::Readme is that a README file that is simply a version of the module documentation isn't all that useful. It often lacks important details like the prerequisites or installation instructions, and it includes a lot of unnecessary details about functions and methods.
A README file should be short and sweet: a synopsis and description, installation instructions and requirements, links to issue trackers, source repos and author/copyright info.
As I am rewriting this, I am wondering if the installation instructions are necessary now?
Many distributions have a generic INSTALL file, generally created by something like Dist::Zilla::Plugin::InstallGuide.
Before Dist::Zilla was as widely used, another option was to add installation instructions to the README file, usually with a few boilerplate along the lines of
perl Makefile.PL
make
make test
make install
or the equivalent for Module::Build.
But this seems unnecessary. Most people are not installing modules that way.
Usually they are using a tool like cpan, cpanm, cpm or even carton. And there's arely anything unusual about a module that requires specialised installation instructions.
The only use case I can think of is to document non-Perl external libraries that are required. But that can be overcome using Alien modules or adding a separate REQUIREMENTS section to the README.
I am considering removing the generic INSTALL file from modules.
I am curious as to what other people in the Perl community think about this.
Is it still worthwhile to add generic installation instructions to distributions nowadays?
I was born on the Moon but kidnapped by astronauts and raised in the suburbs of Grumman. Eventually, I drifted along the Gulf Stream to Northern Europe.
I suspect it would be best to point to instructions for generic perl module installation, which could then provide various options (assuming you have author have decided to prescribe to them... which you likely have implicitly via MakeMaker or friends).
Which itself could simply be a pod-only module on the CPAN.
I think it's still worth it, and it's not causing problems to include it. I have this in my READMEs.
You can install this module with a CPAN client, which will resolve and install the dependencies: % cpan Tie::Cycle % cpanm Tie::Cycle You can also install directly from the distribution directory, which will also install the dependencies: % cpan . % cpanm . You could install just this module manually: % perl Makefile.PL % make % make test % make installHonestly, I'd keep them. They take up very little space in the grand scheme of things and if having them helps prevent one person from just manually copying files around (which still happens with alarming frequency) then they have already been worth it.
I’ll take this opportunity to plug my Pod::Readme::Brief, which generates a README roughly along the lines that brian suggests. You can look at its own README for an example of its output.