Should support (upstream?) Zhaoyuan's tutorials

[EricCousineau-TRI]

Many people find @guzhaoyuan's tutorials[1] useful, and it would be nice to have those incorporated into Drake-proper docs. I like the writing style of bottom-line-on-top, and generally giving what is needed.

I do fear some level of bit-rot, but I think it's something that we can def. manage if we allocate resources correctly.

@RussTedrake Who would be appropriate to assign this to?
I would like to remain focused on the Python aspects of Drake, and help with multibody + geometry improvements as they help our team.

FYI @sherm1

Relates #12912

[1] https://drake.guzhaoyuan.com/

[sherm1]

Assigning to @ToffeeAlbina-TRI for disposition.

[IanTheEngineer]

I chatted about this with Russ & Eric via email. I am interested in taking on integrating Zhaoyuan's tutorials with Drake's documentation. They're particularly useful from a "Getting Started" and "Drake Conceptual Overview" perspective.

I'd be happy to take pointers from folks on how to best integrate these docs with our current documentation flow.

[EricCousineau-TRI]

One approach to consider is to try and map the concepts and general API onto our existing Tutorials in Jupyter Notebooks. It will not necessarily cover the exact same material (e.g. Bazel building, C++), but will give an entry to the API overview.

You can also look at what Russ and his students have published on Underactuated as well - in his textbook, and in the related notebooks?

[sherm1]

IMO it would be nice to keep this as a C++ tutorial since we are very short on those.

[EricCousineau-TRI]

If the goal is to merge it with Drake docs, my preference is Python, as that's what we currently have the mechanisms for tutorial documentation and testing (vs. just example programs and unittests).

I disprefer C++ as it requires more overhead to solve (the testing side of things) - but will leave it up to Ian to decide.

[sherm1]

Do you think the Python tutorials are adequate for teaching C++ users as well?

[EricCousineau-TRI]

For teaching the high-level concepts of Drake, yes, I think so. @RussTedrake has shown the necessary concepts of Drake in Python in his underactuated (class + textbook) + manipulation (class).

For C++ specifics, maybe not, but I think it's higher overhead than it's worth at this point. Generally, users delving into C++ seem like they already have good knowledge of C++ and can easily adapt from Python (which has about the same API, by design) to C++.

[SeanCurtis-TRI]

My passing thought is this:

If the goal is to teach Drake concepts, then python. If the goal is to teach C++, then C++.

The python version has much higher Drake-unique information density than the equivalent C++ version would.

[EricCousineau-TRI]

To follow on Sean's comment: My goal for this would be to namely teach Drake.
C++ / Bazel / CMake can come in other (possibly better?) forms.

[IanTheEngineer]

I think that tutorials should cover both C++ and Python usage. At the end of the day, folks that come to Drake are interested in the powerful functionality & libraries offered here, and we need to meet them where they're at.

For some users, that preference will be C++ and others Python. Just by sheer numbers and relative language complexity, most of them will likely start as pydrake users. I hope we can eventually get to the point of ROS' roscpp and rospy tutorials, in that they present both supported languages side by side.

With that said, @guzhaoyuan's tutorial focuses on overall "getting started' concepts, and then on some C++ examples. I'll use this as a starting point.

[RussTedrake]

I mostly agree with everyone's comments. We've always said that folks that know C++ well enough to be successful are much more likely to be able to translate from Python than vice versa.

Also the value of getting to try out drake with non-trivial examples without even downloading the binaries (via binder/colab) has proven incredibly valuable. The drake installation is intimidating -- even for binaries (because of the large list of prereqs).

So I definitely favor getting compelling python tutorials first.

[EricCousineau-TRI]

@IanTheEngineer On a count of practicality, I would strongly recommend against trying to go the C++ route, unless you want additional overhead of instrumenting the documentation (and testing) for it.

[IanTheEngineer]

Thanks for your perspectives, all. Taking them into consideration, it likely makes sense to start along the same lines as Zhaoyuan's "getting started" pages and then weave in the already-existing pydrake tutorials.

I do think we're missing C++ tutorials on how to construct a C++ Drake-enabled system, but perhaps that could be done separately from the beginners tutorials (or during a second pass).

[EricCousineau-TRI]

Currently labeling this as a component: jupyter. Feel free to change it if you go a different solution route.

EDIT: On second thought, scoping this label down to just infrastructure: #13208 (review)