Two points in reply to try to help you understand why you're seeing these problems.
Firstly, it's almost impossible to get developers working on a project in their spare time to work on documentation. Any spare time they get to play wouldn't be spent on writing documentation, it's just too boring. Trying to force people to write docs would just drive them away, so it's sort of a catch22 situation. When a project gets larger, they hopefully attract technical writers who can fill this void.
Secondly, this is an NT operating system. There is more documentation already written for NT than you could ever dare to read. If you know the area you're working on then things should start to make sense when you have the code.
Let's take the USB project you mentioned. I know people hate it when this answer is used, but knowing how to write NT drivers and having the source code for the driver, plus having a specification to reference is generally enough. Driver devs know the Windows driver model and how it works, so that's half the battle. There's a vast amount of official documentation for the USB standard, so that's taken care of too.
In industry, documentation is generally used because the engineering behind the project is still being designed, the devs have no knowledge of the architecture of what they're writing, only the architecture of what it's running on (windows). Thus, you'll generally see design and interface specs for whatever bespoke engineering project they're working on. But, for the OS itself, they'll have Windows Internals and Driver Model books. This documentation is already written, and this is what we as ReactOS devs also use.
Hope that makes sense
Ged.
-----Original Message----- From: ros-dev-bounces@reactos.org [mailto:ros-dev-bounces@reactos.org] On Behalf Of Maya Posch Sent: 30 October 2008 15:24 To: ReactOS Development List Subject: [ros-dev] Regarding documentation and attracting new developers
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
_______________________________________________ Ros-dev mailing list Ros-dev@reactos.org http://www.reactos.org/mailman/listinfo/ros-dev