INSTALLs in the package and wiki-documentation

[Cube]

In the last time there were some problems because the install- and upgrade-manuals in the package and in the wiki are different. The devs normally only update the INSTALL-file, not the wiki. There are also specific INSTALL-files for each distro, in the wiki that's missing. At the moment there are many differences between the package- and the wiki-instructions. Even if both version work, this makes maintenance of the documentation difficult.

So I would like to discuss here this topic - perhaps we can find a better solution.
I see the following possibilities:
- We could delete the manuals for installation and RCx->RCx upgrade in the wiki and point to the INSTALL-file.
- We could copy all the different INSTALL-files into the wiki - then we have to update it if there is a change in the INSTALL file.
- We could also make a link to the wiki in the INSTALL-file.

[pgentoo]

I propose putting a message in the INSTALL file that references the appropriate wiki page. It's easier to keep the wiki updated and accurate...

[BioALIEN]

I agree with pgentoo's comments and choose:
"- We could also make a link to the wiki in the INSTALL-file."

The INSTALL file should list a very generic installation, e.g. how to download the package, extract the files and execute the install.

The rest is a link to the wiki that guides the person through the install procedure.

The same would be good for upgrade. In fact, if we use this method, then INSTALL and UPGRADE files would be almost identical.

[gOOvER]

Also agree with pgentoo. So it's easier to keep all Up2date

[RatS]

I disagree. It's normally me, who upgrades installation and upgrade. to rewrite the INSTALL file is no problem for me. However, to edit the docu page will create more overhead.
Best solution will be: To install or update start: ispcp-setup (However, this hat to be written first)

[kilburn]

I also disagree. The instructions may change from version to version, so consider this use case:

- Peter wants to install some older version for whatever reason
- Peter downloads the version he wants
- Peter checks the INSTALL instructions

1- INSTALL points to the wiki, and the wiki only has install instructions of the newest release, so peter ends up with a failed installation.
2- INSTALL has the installation instructions of this version, so peter ends with a working system.

See my point? INSTALL is version-specific so it should be bundled with each realease...

[gOOvER]

We don't support older Versions. When User A want's to install an older Version, he have to look on his own, how to install We can't support all Versions.

[kilburn]

Supporting older versions is one thing, getting rid of it's installation instructions is another one...

[Cube]

I also think there should be a manual included in the package. That's the case with most other software too. Also we can not guarantee, that funny guys do not modify the wiki so that it does not work. Even if we recognise that very fast, this will result in failed installations.
I personally would prefer that there are only the INSTALL-files. I also think it's not that much work for the docu-team to copy changes from the INSTALL-files to the wiki. But in this case that manuals should not be editable by others (I don't know if this is possible with our wiki-software), so that there are always the same instructions in the wiki and in the INSTALL-file. We definitely have to get rid of these two different versions we have right now.

[Cube]

So at the moment there are 3 people who like the wiki solution and 3 who like the INSTALL solution. Let's try to make both groups happy.

Quote:(I don't know if this is possible with our wiki-software)

I now know, that this is possible. The edit-permissions for the install and upgrade pages can be given only to the docu-team and to the devs.

So I would make it this way:
- delete actual wiki-manuals
- copy all distro-specific install and upgrade manuals from the INSTALL-files to the wiki
- add a sentence, that this manual is for the most recent release and that instructions for nightly builds or older versions can be found in the INSTALL-files
- restrict editing of these pages (has to be done by superuser gOOvER)
- the docu-team will update the wiki if RatS/devs make changes to the INSTALL-files and there is a new release

Any doubts/objections?