Separating documentation for Python and blocks?

[dmusican]

I'm teaching for a summer program that's doing Python programming in pybricks. It's awesome just as it was for us last year!

One thing that has changed since last summer is that the documentation now shows all of the information for the new coding blocks. We're not using blocks ourselves, and thus I find that the documentation now appears more cluttered than it used to. There's something about the visual presentation of the blocks in the documentation that calls attention to themselves. They become the first thing you see... but I want them to be the last thing my students see, because we're doing straight Python programming. As they are beginning programmers, the extra overhead of the blocks being there is confusing.

I'm sure that it must be dramatically simpler to maintain a single combined version of the documentation than to have two separate versions of it, so I'm aware of the unreasonableness of this request. Nonetheless, would it be worthwhile to think about having a Python-only (or blocks-only, I suppose) version of the docs so that students doing Python coding don't get distracted by the blocks?

Maybe there's a creative form of CSS styling where it could be managed with a toggle?

[laurensvalk]

I'm teaching for a summer program that's doing Python programming in pybricks. It's awesome just as it was for us last year!

Thank you, we're glad to hear it!

(...) would it be worthwhile to think about having a Python-only (or blocks-only, I suppose) version of the docs

Yes, it would be nice to have separate versions of documentation.

I'm sure that it must be dramatically simpler to maintain a single combined version of the documentation than to have two separate versions of it, so I'm aware of the unreasonableness of this request.

This has indeed been the approach thus far. We wanted to make sure we at least had something comprehensive from the start, even if the presentation could be better. (One of the problems with the official Powered Up app is that it has no documentation at all.)

At present, I am working on a new beginner's guide that focuses primarily on block coding. The first chapters are already live. This won't be quite the same as documentation since it's more like a how-to guide, but it's a step in the right direction. Maybe it can have a few additional chapters which might act as lookup documentation. When we have that, we could remove the blocks from the Python documentation.

(Side note --- the beginner's guide will soon feature a starter robot that should be fun for Python lessons too. Or maybe I should write a complementary guide dedicated to Python too... 😄)

But in the meantime, perhaps you could use the 3.3.0 version of the documentation which did not yet feature the blocks. If you're not using the XboxController or Car classes, you might find this version to be complete enough. Making separate builds of the documentation would be quite easy too, but I would rather just remove them altogether as described above.

If you ever decide to try the block coding feature, I'll be curious to hear what you think. It's designed to very closely match the Python experience, and generate "nice" code, avoiding lots of glue code just to make it work. You can also write Python functions in a Python file and use that in your block code, or vice versa.

[dmusican]

Thanks for the link to the 3.3.0 documentation; that's great. I'll likely have our students bookmark that in their browsers today.

From my brief looks at the block coding feature, it looks great. It's fabulous that it mirrors so cleanly with the Python version.

For our purposes, the summer program that we do involves four different course sections, each of which use Python for entirely different technologies and subject areas. Students swap each week from one section to another, in different orders. So some of them start with me in the robotics section using pybricks; another set of them start next door working on computer vision in Python using OpenCV, etc. Then in week 2 they all swap around, and then again in week 3. So I'm pretty committed to using Python coding as opposed to blocks, even for the beginners, so we can symmetrically move people around and enable them to have similar transitions as they move from one section to another. But I absolutely see the strong value in the blocks for the right situations.

[laurensvalk]

Sounds good! If any of your other (future) projects use MicroPython such as on some OpenMV boards, you can link them wirelessly to LEGO hubs quite easily for their final integration project :) --- https://pybricks.com/project/micropython-ble-communication/

[JudeAbbey]

@laurensvalk loving the block code is for my primary students , but also have kids that should be transitioning to text coding.
So any idea when you'll add some more chapters to the new beginner's guide Block code documentation?
What guide / tutorials will you recommend beginners using pybricks python?

Thank you
Jude

[laurensvalk]

Thanks @JudeAbbey !

I don't have a specific timeline for the new chapters but we are working on them.

As for Python guides, I suppose it depends a bit on the path you want to follow. I.e. either start with blocks and transition to Python, or directly start in Python.

Even if you're using it for competitions, it can sometimes be fun to take a break and pick another fun example project, such as from here or here. Many of the skills you'll learn will also be applicable to the competitions.