Improve new contributor's experience

I want to make the project easier to understand for new contributors. I think the most important thing is adding code comments, followed by adding more tutorial-type content in readthedocs for different use cases.

Code cleanup would also be good, but it will require more testing effort. Documentation/comments seems like low-hanging fruit.

This raises the question of where to put the canonical, most-detailed description of each PC->CF command. As far as I can tell, there is no single friendly place where a new contributor can learn “these are all the commands I can send to the Crazyflie”. The CRTP documentation is pretty close, but it might be a little bit low-level - for example, it forces the contributor to read about the integer quantization of the full-state setpoint, which is abstracted away from almost all of the PC side.

Some options:

• crazyflie_cppcomments. crtp.h might be the most cohesive and trustworthy source of truth for the Crazyflie’s radio protocol; the crazyflie.h method declarations abstract away the exact data formats.
• ROS service definition comments. I would lean away from these, since from the perspective of the Crazyflie itself and the perspective of the high-level script writer, use of ROS is an implementation detail.
• crazyflie_server method definition comments. Also seem a little too closely tied to ROS.
• pycrazyswarm wrapper method definition comments. Probably the most convenient place for Crazyswarm script writers, but maybe not discoverable for non-Crazyswarm developers.
• crazyflie-firmware code comments. Unfortunately, the radio packet definitions are spread all over the code, so this fails the “single friendly place” criterion.
• some neutral Bitcraze documentation location, like the CRTP documentation above. Big advantage: has more contributors, easier to get Bitcraze employees to contribute.

Any opinions?

[jpreiss]

https://documentation.divio.com/

This is an interesting resource on writing good documentation. They suggest that software should have 4 kinds of documentation: Tutorials, How-to guides, Reference, and Explanation.

I think the content in our docs is pretty good, but maybe it could be organized more effectively. For example, the streaming setpoint mode tutorial is predominantly a How-to guide:

A how-to guide is an answer to a question that only a user with some experience could even formulate.

but it’s mixed together with motivations of the Crazyswarm design (as mentioned by hanzheteng above), which would be Explanation.

[jpreiss]

#293, #294, #295 apply some of these ideas, focusing on the setup/tutorial stage.