Improving user-friendability: a Wiki

[ffasilva]

Hi @dqrobotics/developers,

Even though we keep a well documented code, the DQ Robotics still not exactly friendly to new users. We do have repositories with examples, like the matlab-examples, but even them don't give the user a whole lot more than more comments inside a main file.

As such, I would like to volunteer to start a Wiki for our main page, if you agree this is a worthwhile effort. The organization I'm envisioning would be:

• The Wiki will be as code-agnostic as possible, focusing on explaining the basic structures of the library. When unavoidable, it will fallback to MATLAB code snapshots (at least for its first version);
  • Rationally: The idea is to walk users through the classes and their interconnections. For instance, how to create a simple manipulator given its D-H parameters and then use it in one of our controllers.
• Each language will have their version of the exact same examples (e.g., a simple pseudo-inverse control using a Panda arm: MATLAB, C++, Phyton);
  • Rationally: The library is the same in all available languages anyway, so no reason to not be user-friendly here.
• Unification of the language repositories with their examples (i.e., code on matlab-examples would be transferred to a folder examples in matlab);
  • Rationally: The example repositories don't add much in terms of helping the user on their own, so they could be folded into the language repositories.

The idea of the Wiki is not to replace the tutorials, although it will be a good place to introduce them to the users.

What do you think?

Kind regards,
Frederico

P.S.: We could think about migrating the Wiki to the website in the future, but it will be probably easier to create content in the wiki format at first.

[bvadorno]

Hi @ffasilva,

Providing documentation is always good, albeit very time-consuming, so don't underestimate the time you'll spend on this task. As the one who provided almost all documentation and examples for MATLAB, I know firsthand how long it takes.

The Wiki will be as code-agnostic as possible, focusing on explaining the basic structures of the library. When unavoidable, it will fallback to MATLAB code snapshots (at least for its first version);

Agreed.

Rationally: The idea is to walk users through the classes and their interconnections. For instance, how to create a simple manipulator given its D-H parameters and then use it in one of our controllers.

This part is unclear. Do you suggest signposting users to the tutorials, or including examples in the wiki about how to create the model and use the controllers? If the latter, how will this redundancy be helpful?

Each language will have their version of the exact same examples (e.g., a simple pseudo-inverse control using a Panda arm: MATLAB, C++, Phyton);

Rationally: The library is the same in all available languages anyway, so no reason to not be user-friendly here.

Agreed. The caveat is that neither Python nor C++ have plot functionalities yet. Implementing them robustly will not be trivial or quick.

Unification of the language repositories with their examples (i.e., code on matlab-examples would be transferred to a folder examples in matlab);

Rationally: The example repositories don't add much in terms of helping the user on their own, so they could be folded into the language repositories.

That's not a good idea because of our library update policy. For example, currently, if we include new examples but the library remains the same, the version doesn't change and we don't need to release a new version in the release branch. However, if we do as you suggested, we'd have to change the library's version every time we add a new example. We can easily solve your concern in the future by having different installers on pip, homebrew, etc., in which users can choose the full installation, including examples, or a slim installation without examples. This is common practice on Linux, for example.

P.S.: We could think about migrating the Wiki to the website in the future, but it will be probably easier to create content in the wiki format at first.

I don't think the website would be a good place to host this, but Readthedocs might be suitable.

Kind regards,
Bruno

[ffasilva]

Hi @bvadorno,

Providing documentation is always good, albeit very time-consuming, so don't underestimate the time you'll spend on this task. As the one who provided almost all documentation and examples for MATLAB, I know firsthand how long it takes.

I'm not! I'm thinking of this more as something I'll be incrementally working on than something I'll deliver in the next X months.

This part is unclear. Do you suggest signposting users to the tutorials, or including examples in the wiki about how to create the model and use the controllers? If the latter, how will this redundancy be helpful?

I'm envisioning the Wiki as something in-between the code documentation and the tutorials.
New users tend to have a hard time figuring out what features are available in the library. For MATLAB, we have the help command to assist them, but C++ and Python users don't have access to this interactive feature.
Another point is that tutorials are hands-on activities, which require them to be instantiated to one of the languages. The learning-dqrobotics-in-matlab/robotic_manipulators does an amazing use of MATLAB live script to guide users from modeling to control, but it requires C++/Python users to (have access to and) download MATLAB.

The Wiki could be a place where new users could have easy access to how the library is structured and what it can do in a less strict way than a code documentation. It would also be a good place to signpost users to the tutorials and examples (see my later comment). The idea is not to repeat the tutorials, but having a more "informal" format, the Wiki could incorporate some minimal examples within the explanations.

Agreed. The caveat is that neither Python nor C++ have plot functionalities yet. Implementing them robustly will not be trivial or quick.

I wasn't thinking about missing functionalities, to be honest. Here, I was thinking that if one example teaches the user how to do A in MATLAB, we should aim to have examples teaching A in C++ and Python as well, language limitations/adaptations aside. Language limitations will surely prevent examples from being as visual in all versions, but things such as printing the end-effector pose or the norm of the error can be done in all of them.

That's not a good idea because of our https://github.com/dqrobotics/developers-playground/discussions/4. For example, currently, if we include new examples but the library remains the same, the version doesn't change and we don't need to release a new version in the release branch. However, if we do as you suggested, we'd have to change the library's version every time we add a new example. We can easily solve your concern in the future by having different installers on pip, homebrew, etc., in which users can choose the full installation, including examples, or a slim installation without examples. This is common practice on Linux, for example.

I was expecting this separation to have some motivation I couldn't place. My concern is that, with this organization, I've seen plenty of new users (and surprisingly enough, experienced users as well) who had no idea we even have examples/tutorials in different repositories.
Perhaps having an installation that alerts users of a full-package option with examples can solve this, but having a Wiki that directs them there could also help.

I don't think the website would be a good place to host this, but Readthedocs might be suitable.

I consider the Readthedocs as part of the website. The only reason I don't want to start this there is to avoid dealing with aspects related to website design, whereas the Wiki can be an easier way to create content right away.

Kind regards,
Frederico

[bvadorno]

Hi @ffasilva,

New users tend to have a hard time figuring out what features are available in the library. For MATLAB, we have the help command to assist them, but C++ and Python users don't have access to this interactive feature.

Python has a built-in help function similar to MATLAB's. C++ doesn't, indeed, but I'm more concerned with its documentation now.

Another point is that tutorials are hands-on activities, which require them to be instantiated to one of the languages. The learning-dqrobotics-in-matlab/robotic_manipulators does an amazing use of MATLAB live script to guide users from modeling to control, but it requires C++/Python users to (have access to and) download MATLAB.

That's okay, but bear in mind that there are plans to translate the tutorials into Python.

The Wiki could be a place where new users could have easy access to how the library is structured and what it can do in a less strict way than a code documentation. It would also be a good place to signpost users to the tutorials and examples (see my later comment). The idea is not to repeat the tutorials, but having a more "informal" format, the Wiki could incorporate some minimal examples within the explanations.

The RAM paper already describes the library structure, but I agree we can make it even more comprehensive on a wiki page. Just ensure that you are not reinventing the wheel.

My concern is that, with this organization, I've seen plenty of new users (and surprisingly enough, experienced users as well) who had no idea we even have examples/tutorials in different repositories.

Unfortunately, our academic world is full of unpleasant surprises. What you describe is another thing that has frustrated me in the 13 years since I first released the library publicly, especially because we mentioned the examples in the RAM paper. People from my group don't read it, which is appalling.

Perhaps having an installation that alerts users of a full-package option with examples can solve this, but having a Wiki that directs them there could also help.

A warning during the installation part would be a good idea. Signposting in the documentation is also good. Furthermore, people can always improve the documentation through pull requests. What I'm saying here is that a Wiki is not an excuse for poor code documentation, which is currently happening in C++ and Python.

I consider the Readthedocs as part of the website. The only reason I don't want to start this there is to avoid dealing with aspects related to website design, whereas the Wiki can be an easier way to create content right away.

There is no web design in Readthedocs, and it's actually very similar to Markdown. It's not the same as the website because they are hosted in separate places, the update/edition mechanism differs completely. In other words, they are completely different things.

That being said, you can go ahead with the Wiki. Just ensure that you are not duplicating information unnecessarily because it might confuse people and give me and @mmmarinho more work to revise and amend things, which I don't want.

Kind regards,
Bruno

[mmmarinho]

@ffasilva
Brief addition to the discussion.

I think after you start drafting your suggestion in the Github wiki, although powerful, you'll quickly find out its weaknesses.

reStructuredText and Sphinx (and by consequence vanilla ReadTheDocs) tend to be better for this task because, for example, you can add tabs to switch between languages without breaking the narrative, has lots of freedom adding code snippets (highlighting, splitting lines, numbering) etc.

@juanjqo has been trying to fix the MathJax in the ReadTheDocs page. If that works well, you'll notice that we can use the macros we are all used to write the documentation. As the person who wrote the entire MATLAB live scripts tutorial without using macros, let me tell you that it wasn't fun nor time-efficient -- I simply had no alternative. If you can help him figure it out, I think we'd all benefit greatly from that. Basically, the context of this advice is that I believe that when you said "explain code-agnostically" you meant using math alongside code.

Although at first glance starting something new might sound like the answer, it often isn't, and I'd like to cite "Chesterton's fence"

reforms should not be made until the reasoning behind the existing state of affairs is understood

Cheers,
Murilo

[bvadorno]

@mmmarinho, kudos for the Chesterston’s fence quote. I didn’t know it but will definitely incorporate it to my repertoire.

@ffasilva, take those pieces of advice seriously. I’d say that almost if not all things in the library have been comprehensively discussed and well thought. If you don’t see the point of something, like the separation of examples from the main code, don’t assume it’s a byproduct of careless design.

That been said, I encourage you to improve the overall documentation. As @mmmarinho said, fixing the macros on Readthedocs will be a huge plus, especially because what you want to contribute is perfectly aligned with the current Readthedocs documentation.

Kind regards,
Bruno

[bvadorno]

@ffasilva, have you considered helping @juanjqo fix the MathJax on the ReadTheDocs page?