30 Oct
2008
30 Oct
'08
4:01 p.m.
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(a)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(a)reactos.org
http://www.reactos.org/mailman/listinfo/ros-dev