Report on the robotology software installation procedure #933
Comments
First of all, thanks for the detailed report! This is gold. Anyone working too much with robotology-superbuild or the rest of our software stack will be inevitable be affected by the so-called expert blindness. If for you installing the software takes such as long time, that is essentially a bug exactly like any other software bug that could affect the robotology-superbuild, so it is important to try to fix it! On the other hand, the documentation is meant to target different kind of users with different backgrounds, so we try reach the best trade-off of helping all of them, without scaring any of them too much.
Indeed! Just to clarify, at this point you could install any library you are interested (I am mentioning just a few MATLAB-library you could be interested in, see https://anaconda.org/robotology/repo/files for more available packages) in with: Then you can just open MATLAB in a termainal where you called I will address the rest of the report point by point in future comments. I will number all the different points/aspects to track them easily. |
P1: Introduction section
All those details were probably there when the superbuild was only meant to be installed by source and not by binary installation (and then, you really needed to know what CMake is!) and to properly acknoledge YCM without which all the machinery of the superbuild would not be possible. To be perfectly honest, a bit of the focus on the paper there is to make sure that people properly attribute the paper if they use the superbuild in academic works, but probably it is metter to explicitly specify that. Proposed Action:
|
Can you check if #932 improves this aspect? |
P2: Superbuild sectionLeaving this section before "Binary Installation" was probably an error done in #852, especially until we have an easy way (an documentable in a eay way) to install a specific distro with conda (see #727). For the time being, we can just move this section under "source installation". Action point: |
|
Ah, I just realized that I am missing a fundemental information here. @DanielePucci Why did you wanted to install the robotology-superbuild/related software? What did you wanted to do? |
|
Hi @traversaro, sorry for taking so long to answer: I wanted to reserve some time to this task, and the Christmas break helped in this sense.
Thank you for your understanding, the report wanted to be a different standpoint on something that - for sure - is working out for many of the experts.
Sure, this is also understandable: finding a trade-off for sure is not an easy task.
This is super cool, I did not realise I was that close! I did it and it seems that it worked out although I am not sure that the text, e.g., is actually saying that it went fine - see below for details. Click to see the output details (sorry, I mistakenly cleaned the terminal so the following is the output of the second instance of the commands above)
I did this but although I had matlab installed, it seems that I do not have the command Once opened, I opened Simulink by clicking on the button. After that, I opened the Simulink library and I looked for, e.g. Whole-Body Toolbox, but it seems to me that I did not find any. So, probably I am missing something
Great! |
I see, it made sense back in time I would say
Roger, I also agree that it would be better to add the explicit mention to that even in the beginning, like a short section called How to cite robotology-superbiuld or something like that
These make sense to me |
It is much better @traversaro, I just approved the PR. What I still notice - but maybe this is just me - is that nesting several READMEs is not helping the user know where he/she is. For instance, what I would suggest is to
or
|
Probably you meant "below" or "after" instead of "under"? |
My original plan was to install the software for making the Yoga++ with iCub 3 - although the other day passing by the lab, I just saw that @lrapetti did it in a couple of hours 😭. In the hindsight, I could have used the one line installation made by @nunoguedelha, which I actually tested -- see #707 (comment) and https://github.com/ami-iit/element_software-engineering/issues/32 By thinking about it, I do not know if it would make sense to somehow profile the users, even with a list of questions like you just did it here, and put this list of questions in the beginning of the README (e.g. do you want to install software to use matlab/simulink and simulate algorithms in Gazebo?). And then, if the user somehow finds the question for himself/herself on the list, a click on the question opens a set of actions/instructions to follow to install the software he/she is interested in. The other reason why for me to install the software, however, was to have that old feeling of having the entire |
|
Today I followed the installation procedure for the sources of robotology-superbuild, the software package we use extensively in our research line @robotology/iit-artificial-mechanical-intelligence. I wanted to come back to this since I received a new laptop and I didn't even have the brew nor the git installed, so it seemed to me I could be a good testcase of someone not aligned with the recent development or of someone that just arrived in the lab. I have to say that the improvements of the installation procedure was substantial: it is now clear, linear, and straight to the point. So, thank you very much @traversaro for having taken into account the comments above. By considering the effective time I dealt with the installation, in about 20 minutes I completed the task, from installing brew, git, the robotology-superbuild, and launching Gazebo. Being on Mac, the only setback I had was due to #916, both when installing the dependencies and during the compilation. Thanks to the @traversaro quick help, I could quickly overcome the issue during the compilation. To further simplify the installation procedure for Mac users, I opened #1394 that details the passages that I performed when installing the software. At this point, I close the issue. Thank you all. |
Hi all, today I decided to (re-)install the
robotology-superbuild. I honestly acknowledge that it is a long time since I last installed it being pretty much busy with other businesses over the last two years. So, thank you very much for all the effort and continuous improvement.However, I wanted to report my experience and feelings while trying to install the software. On the one hand, I want to apologise in advance if I missed something trivial during the installation procedure; on the other hand, I believe that I could be a good use-case of users that are not up-to-date with the technical details. For the latter reason, I decided to write this report: I think it is worth the risk of appearing shallow or not updated.
During the attempt at installing the software, I experienced many feelings that I also wanted to report. Probably, how people feel has an impact on how quick they drop the attempt of installing our software, and we would like to avoid this as much as we can. I categorise these feelings with keywords, but I associated them with emoticons, so during the report you can quickly see how I felt:
I-am-dumb😧This-is-super-cool🥳Is-this-really-necessary?🤔I-am-scared😟I-am-bored😴I-give-up😫When I have, I also wanted to provide suggestions for improvements - clearly, these are suggestions that you can decide to rule out. In these cases, I use
🟡 Suggestion
To provide the reader with a detailed and sincere feedback, I go through the robotology-superbuild README of this commit (the latest to date). So, let's get started.
At this point, I clicked on CMake and YCM. I knew the basics, but I clicked and starting looking at these pages randomly. This is fine, but the user is already loosing time on something that - at the end - he does not want to do: he/she just wants to install software. You may think: it is your fault if you clicked. Yeah, but to help users avoid loosing time and going to the point, we may
🟡 Add a
Referencesection at the end of the README, and we can cite sources with something like[1, 2], where 1 and 2 are not hyperlinked there, but below in theReferencesection. By doing so, we may help the reader keep the focus.After thinking better, I am not sure if adding the details that the superbuild uses CMAKE and YCM is necessary here 🤔 At the end, at this point we are not suggesting the reader to do some action (i.e. check if you installed CMAKE) but just saying additional information that it is not really clear to me the purpose of (at this point specifically).
I thought, this is super cool, three clicks and I am done 🥳
If people do not know YARP, or they want to know it better, they may start googling for it 🤔. Furthermore, since YARP is basically necessary to run iCub, probably
🟡 we may just leave the sentence
such as the software used to run the iCub humanoid robot.The hyperlink (twice in two paragraphs) is really suggesting the reader: "hey, you gotta click if you did not do it before, and check the amazing site of CMAKE out!"
🟡 I would remove the hyperlink. Sincerely, however, I would remove the entire paragraph below
I felt that the documentation really wanted to inform me about CMake and YCM. But really wanted me. On the one hand, I was not understanding the purpose of these information 🤔 on the other hand, I was not really interested in these details, so I perceived a pedantic will of the documentation. As a consequence, I started interpolating 😴
Probably this was me, but the will of documentation of telling me about YCM here got a little disturbing. It was like someone telling me repeatedly to read about additional details. So, I started and I opened these pages. In a second, I was scared since the amount of things to read was a lot 😟 And I still did not understand if it was necessary to read all this stuff 😧 : I just wanted to install the software, as probably most users would like to.
🥳 🥳 🥳
At this point, I wanted to jump to the Binary Installation section, but I was a little worried - from the section before - that I might have missed information, so I went through the Superbuild section 😧 😟
This was cool 🥳 but I felt that these info were somehow redundant with respect to those of the previous section. Furthermore, analogously to what we mentioned before,
🟡 we could remove hyperlinks and transform them into references
These titles made me worried 😟 : I did not know if I had to understand all the details for the installation (they seem to be talking about important and related topics) but I was not sure about this 😧
🟡 Besides the typo in
tipical, I would remove this sentence that looked long and articulated. The sentence next explains pretty well the point, namely.🟡 Just remove the comma before "that specify"
Okey, here I felt dumb 😧 so I opened
doc/cmake-options.md#profile-specific-documentationto read more, which made me scared 😟 😟 since I found many profiles and I did not know what I should have read/understood. For this reason, I interpolated 😴 and moved forward, but I was not sure if I should have read all of that.I was not understanding why this was necessary at this point 🤔
I started reading about Rolling update 😧 Probably, I lost more time here
I felt a pedantic will of the documentation. On the one hand, these info seem not interesting/related for my purpose 😴 on the other hand, I felt dumb because I should have understood probably all the micro details before the installation
Hey, I want the advanced stuff 🥳 ! So, I opened
doc/change-project-tags.mdbut then I got scared about the micro details and other hypelinks to read 😧 😟 For this reason, I skipped 😴 but I was not sure if I should have read all these micro details for the installationThis was fine, although the many hyperlinks are always a subtle invitation to the reader to open them since he/she is not sure if he needs to know all the details to install the software 😧
At his point I was happy 🥳 but I was also a little tired. It was probably already 20/30 minutes I was on the website. And I did not even start. I was also worried that I did not understood some micro details above was necessary for what was coming 😧
The presence of these links are tempting for non-expert users since they feel dumb 😧 and they may think that for what comes next (installation) they need to know all the content they are pointing
🟡 I would add a relief sentence for non-expert users. Like: hey, if you are not a ninja in conda, do not worry, we take care of the details and you do not need to go through them
Or something like that. Few times, I have had the feeling that the documentation was for king/ninja open-software conda developers and that you either are at that level, or you do not go through. This was scaring me from times to times.
Okey, here was the moment of being lost in the dark 😧. I am asked to read
doc/conda-forge.md, and in particular the sectionBinary Installation. First, I was not sure that this section belonged to the same document, so I had to open two tabs. Anyways, I started fromdoc/conda-forge.md.The document
doc/conda-forge.mdis very long, which made me scared 😟 and I already was a little tired, so this was the first moment I thought: I give up, it is too complex and time consuming for me 😫 In particular, the documentdoc/conda-forge.mdstarts with a long and pedantic list of prons and cons ofconda-forge.Guys, I trust you since you are the kings of open software and CI, so really, I just want to install the software. I lost here other 10/15 minutes probably to understand the details 🤔
Now, I am at
Binary Installationsection.Here, I am pointed to
robotologyconda channel, which I opened up, took a look, did not understand what I was looking at, and I closed. I did not understand what I should have done there, or if it was a mere references. So, I had the impression that I just lost some time, and I moved on.Here I was really confused. I did not understand - so I felt dumb 😧 - if I had to go through all the docs and details in the documentation on CMake options to get the installation lift off. Clearly, as soon as I opened the doc, I was really scared 😟 since the document is huge. So, I decided to ignore it - I was not really sure about what I was doing - but this left me with a sense of deep insecurity.
🟡 we may just add two three commands to verify if the user has the conda installed, like
I went to
mambaforge, and more specifically to https://github.com/conda-forge/miniforge#homebrew. Since I did not know whether or not I installed mambaforge, I just opened the terminal a launched🟡 I would remove the hypelink to
mambathat I did not know if I had to go throughWhile I was writing this report and after having launched
brew install miniforge, this popped upAfter this, I was able to finish the installation
Click to see the installation details
Here I was confused. To me, I had just installed miniforge with
brew install miniforgeby following https://github.com/conda-forge/miniforge#homebrew. Anyways, I went toinstall-mambaforgedocumentation, and in particular to https://github.com/robotology/robotology-superbuild/blob/master/doc/install-mambaforge.md#macos🟡 I launched these commands in a terminal, so it would be better to say this
I started feeling that I am doing something I already did, in fact, the outcome of the terminal was
I did not use the -u option. So, I tried to go forward
I launched the command above, and I obtained
At this point, I started thinking that something was not working out. I was tired sincerely: I was probably inside the third or fourth .md file (starting from robotology) and the feeling of being lost was really high. Anyways, I went on.
I then realised that I was using a zsh, so I launched the command, and then I obtained
At this point, I really did not know if what I was doing was making sense
🟡 Probably, if we add the expected outcome of the terminal the user would know more if he/she is on the right way
I launched the command, and did not get any output. I was grasping a little in the dark at that point. But I went forward
At that point, I tried to launch the
conda infocommand, and then I gotThis was a relief moment, after probably one hour and half 🥳 I was lost: I no longer had the feeling at which readme I was and where I had to go back, but the fact that the output was somehow the expected gave me little dopamine to continue
At this point I did,
mamba activate baseBut I did not know what and why I was activating. At that point, I closed https://github.com/robotology/robotology-superbuild/edit/master/doc/install-mambaforge.md but I completely forgot where I was and from where I had to restart.
For this reason, I restarted from https://github.com/robotology/robotology-superbuild and went back to https://github.com/robotology/robotology-superbuild/blob/master/doc/conda-forge.md#binary-installation
Probably, I was here
I was tired at this point, so I did not understand/read quickly these details that seemed not important for my purpose.
Here the documentation is somehow suggesting to read more about https://docs.conda.io/projects/conda/en/4.6.1/user-guide/tasks/manage-environments.html which is a very heavy document and still not really related to my purpose that was to install software
At this point, I was lost since after a couple of hours I did not have the idea of how far I was from actually installing the software (Monia started calling me to do stuff), so was really tempted to give up 😫 😫
I launched the command, and I got
So, at this point I was just doing stuff quickly and trying to get it as soon as possible. I was starving for a list of actions to execute one after the other without narrative
I launched the command and I obtained
So it seems that I had to run
mamba init. I did it, and then I re-launchedmamba activate robotologyenv, but I was not sure about what was going on.🟡 To improve the awareness of the user, it would be better to add the expected outcomes of the commands
At this point, I gave up with the binary installation: it was probably three hours that I was on the task and I could no longer dedicate time to move on although I had the feeling of being close. I hope to have more time in the next days to continue the task. I thought, however, that already this preliminary user-expereince report may give preliminary inputs on how to improve the documentation.
The text was updated successfully, but these errors were encountered: