Define dependency installation documentation best practice

[jgvictores]

Options for documenting dependency installation documentation (note: this all started with https://github.com/roboticslab-uc3m/teo-main/issues/70):

• Linking to official documentation. Update upstream when required.
• Single .md file per dependency.
• One .md file per dependency per OS+distribution version.

cc: @PeterBowman @rsantos88 @David-Estevez et Al... what is your opinion?

[David-Estevez]

I think the best would be a mix between step-by-step instructions and linking to the official documentation.

If the step-by-step instructions become outdated, you can put an issue and there is still a link that you can follow to try to solve it on your own while the documentation is being fixed by the repository maintainers.

I also think that the best place to do this is a single md file, as it is easier to find and to maintain and keep updated.

[jgvictores]

Okay, so then: single .md file per dependency. I'd like to do this in a new repository: https://github.com/roboticslab-uc3m/installation-guides The reason is that, despite #2 (major code reorganization), I believe there will still be repeated dependencies across repositories.

Please:

• Up-vote if you like this idea.
• Down-vote if you think I am proposing the creation of too many new repositories (see #4).

[PeterBowman]

+1 for decoupling any kind of guides from the source code and its documentation.

[David-Estevez]

I have mixed feelings with this one... even though I don't like to have multiple instances of the same guide, since I understand the advantages of having to update and maintain only one guide, I also find more convenient to have all the instructions to install a certain piece of code in that repository.

BTW, with single md file I meant a single file for all dependencies.

[jgvictores]

I understand there is consensus on maintaining our own guides. What remains in doubt is how to organize this.

1. Advantages of a single file for all dependencies (including all OS+distribution versions): 1.1. Easier for beginners: they just copy and paste from a single file. 1.2. Better to specify repository-specific compilation flags (e.g. some required YARP module). 1.3. Avoid yet another repository.

2. Advantages of a new repository: 2.1. Avoid incredibly long files, all with duplicate sections. This is, avoid many files like this file with duplicate sections that must be maintained and can be like this multiplied by the N versions. 2.2. In terms of traceability, better to keep track of what is being treated upstream.

In sight of this, I am going to work on (2), because: (1.1) hasn't been giving any problems on teo-main; (1.2) is not really an issue, just have to decide if repository-specific compilation flags go in the general or local repositories; (1.3) not sure if this is an issue.

Regarding (1.2), I'll see what looks better when these movements start to take place.

[jgvictores]

Starts looking good! https://github.com/roboticslab-uc3m/teo-main/blob/36261d33ef50ead70fbf81d631d5f01d5b22dd43/doc/teo_install_on_ubuntu_14_10.md now has updated cmake installation guide link!

[jgvictores]

Much easier to localize, and then do things like point to the official download page (see CMake installation guide), etc.

[jgvictores]

Would not close this issue until one of the following happen:

• Done everywhere.
• Documented at whatever comes out of #4.

[rsantos88]

Updated links of documentation with new installation-guides repository

[jgvictores]

https://github.com/roboticslab-uc3m/installation-guides is working properly. Thank you all (also @RaulFdzbis who was not in this conversation) for your efforts on this!

Closing issue, all new issues should go in the new dedicated repository.