Comments (10)
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.
from questions-and-answers.
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.
from questions-and-answers.
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).
from questions-and-answers.
+1 for decoupling any kind of guides from the source code and its documentation.
from questions-and-answers.
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.
from questions-and-answers.
I understand there is consensus on maintaining our own guides. What remains in doubt is how to organize this.
-
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. -
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.
from questions-and-answers.
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!
from questions-and-answers.
Much easier to localize, and then do things like point to the official download page (see CMake installation guide), etc.
from questions-and-answers.
Would not close this issue until one of the following happen:
- Done everywhere.
- Documented at whatever comes out of #4.
from questions-and-answers.
Updated links of documentation with new installation-guides repository
from questions-and-answers.
Related Issues (20)
- Make dox target via YCM goodies HOT 9
- Unit tests and unsatisfied dependencies lead to compilation failure HOT 1
- Embrace hooks HOT 3
- Bump required YCM version (v0.10+) HOT 4
- YARP 3.0 upgrade path HOT 5
- Update CMake/YCM export options HOT 10
- [GitHub] Git LFS disabled for roboticslab-uc3m HOT 2
- Centralize Travis scripts HOT 4
- Changes to git branch policy in YARP/YCM HOT 8
- Drop dual master-develop branching in favor of a single prod branch HOT 10
- Review installation-related snippets in Markdown docs HOT 1
- Migrate to GitHub Actions HOT 24
- Add C++ examples to main build HOT 7
- Update links to GitBook project instances on legacy servers HOT 3
- Portmonitors renamed at YARP >= 3.5 HOT 1
- Update links pointing at new subdomain HOT 4
- sp_ineachdb and also sp_msforeachDB return only 50 records instead of hundreds HOT 3
- Randomization problems with JsPsych HOT 1
- cards in Thingsboard professional version HOT 1
- Abandon GitBook, look for alternatives HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from questions-and-answers.