README.md: Keep minimal information with the release

[marcbria]

TL;DR;
On recent versions we are moving from text file documentation to links to the PKP Doc Hub.
URLs will change and will be broken so, for historical reasons would be nice to keep minimal install and config information as text files in the packaged release.

On every version, README.md file is becomming smaller as we are publishing detailed docs in PKP Docs Hub:

• https://github.com/pkp/ojs/blob/stable-3_3_0/README.md
• https://github.com/pkp/ojs/blob/stable-3_4_0/README.md

This is also happening with the /docs folder:

• https://github.com/pkp/ojs/tree/stable-3_3_0/docs
• https://github.com/pkp/ojs/tree/stable-3_4_0/docs

For historical reasons and to let people install older or even relic versions with all the required information, I think we need to keep minimal information packaged with the release.

This minimal information should include:

• Installation instructions.
• Requirements
• Release changes.

What do you think?

[asmecher]

See #7466 for the discussion of documentation removal; in general I think it was a good thing to remove duplicated documentation and focus on the docs hub as the single best place to get documentation.

Release changes are still in the repo in docs/release-notes.

I would support the re-addition of a very stripped down README.md that included system requirements (or a version-specific link to them), and directions to relevant documentation. But I wouldn't be in favour of documenting the installation process; we already maintain too many copies of this IMO.

[marcbria]

I missed the conversation on gitHub. Thanks Alec.

I would support the reintroduction of a very simplified README.md that includes the system requirements (or a version-specific link), and directions to the relevant documentation.

That is the idea.

The whole consersation is more related with "preservation" than how to document soft that is still alive. I mean, would be somthing like... if 5, 10 or 100 years from now someone wants to raise an outdated ojs 3.3 (don't ask me why), where can they find the requirements (hw and sw) and some generic installation instructions? What if we are not in gitHub anymore?

Any links to PKPDocs will be probably broken, so IMO, a minimal, packaged and frozen documentation in the release could be a nice idea... Making clear that the doc is frozen and adding a hightlighted header with "visit this link to the most updated version" in PKPDocs.

I think we agree on the problem (not dramatic and for our future selves) and the only thing would agree is what is meant by "minimal".

But I would not be in favor of documenting the installation process; we already keep too many copies of this IMO.

What do you mean by "many copies"? In PKPDocs we have the big admin manual (that is huge and works well as a reference, but I think nobody is reading it all) and then the README. Am I missing more documents for installation?

About what is the "minimal documentation to be packaged in the release-timevault", I was thinking in something like:

• RELEASE: Including version number and changes (as is now).
• [README.md](https://github.com/pkp/ojs/blob/stable-3_3_0/docs/README.md: With tarball install instructions (as far is the only thing we can ensure they will have in future).
• UPGRADE.md: With versions allowed and UNSUPORTED and also minimal explanations for the upgrade process (again, from tarball, not git).
• [REQUIREMENTS]: With HW and SW requirements. Although HW could be very generic (just an estimation), software need to be detailed, including LAMP versions and required libraries (if any).
• LICENSE: Why do we keep a LICENSE file and a COPYING?

To keep this up to date, first idea I got is create in PKPDocs document with all this. That would allow the documentation to be maintained/updated from DIG (with DEV indications) and you could package it on each release with a simple cut&paste... but if you prefer to keep it in gitHub I'm also ok.