[ros-dev] Regarding documentation and attracting new developers

[Maya Posch]

Gentlemen,

If you don't mind me intruding, I'd like to propose some things I think 
may ease life for us poor ROS devs, existing and new ones :)

First of all, I'd like to suggest 'apprenticeship programming', also 
known by other names, but which commonly involves having one seasoned 
programmer in charge of a particular (sub-)project and one or more 
programmers following his lead. These latter programmers would be less 
experienced but could work on relatively advanced stuff due to the lead 
of the seasoned programmer. This model is commonly used in companies 
already and if adapted for ROS it should make it much easier for 
'newbie' devs to get started, pick up experience and become seasoned 
devs themselves.

My own experience with picking up the USB subproject reflect this as 
well. It's hard to get started without much of a lead, especially when 
one's experience with the NT subsystems is limited. This is also where 
documentation would have helped, bringing me to my second point:

Whenever I start a new project or implementation I first write a 
technical specification detailing the exact layout, APIs and 
implementation. I've heard that this is common practice in professional 
programming as well as other areas. Benefits include having a good 
overview of the project before one starts on it, being able to pick out 
obvious oversights before writing a single line of code, having a 
central place of reference (code does _not_ work for this), allows one 
to quickly pick up on things during maintenance sessions (many months 
later...). It'd also enable the apprentice programming system and make 
it easy for the central project leader(s) to get an overview of the 
progress being made.

Documentation and specifications are often ignored by programmers 
because they're not deemed 'time-efficient', preferring to start 
programming right away instead. In my experience and those of everyone 
in high-level jobs involving anything from programming to hardware 
design (like my housemate who is a senior engineer in a Dutch company 
which designs chips for the telecom industry), specifications and 
documentation are the lifeblood of any project.

I have elected to use both the apprentice method as well as the 
documentation approach in my work on the new installer, bootloader and 
USB stack for ReactOS, attracting two relatively inexperienced but 
highly motivated devs for the installer (RI2, or ROSE) project already. 
They have expressed interest in helping me with further projects in ROS 
as well, even more low-level things. I think that this is a good example 
of the future ROS should be heading towards.

So yeah, that's my rant I guess :)

*ducks and runs for cover*


Maya Posch