31 Oct
2008
31 Oct
'08
8:18 a.m.
gedmurphy wrote:
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.
Not writing documentation/specifications already limits the maximum size
of a project and thus reduces the possibility of anyone jumping in to
fill the (documentation) void. I personally don't like working with
people who can not send me a document on or tell me in a few sentences
what it is I need to know. It gets really tiresome if you have to keep
chasing after people because you need to know something and they're only
available 1 hour for you due to timezones.
If those people do not want to write documentation, fine, have someone
else write the specifications and feed them those. Don't put them in
charge as they clearly aren't thinking about the wellbeing of the
project as a whole but only their small island.
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.
With the USB project I'm having to read a few specs, a dozen books, more
online articles. I don't know how the Windows internals work or even
look like, this is my first time I'm working with them. I find the
available information to be insufficient or at least very poorly
condensed. Yes, the USB spec is very clear, but doesn't directly apply
to the Windows implementation. For that there are other sources, sure,
but they are often outdated, unclear and mostly importantly seldom
directly apply to my needs or explain things in a way a noob like me
could understand. This slows me down immensely.
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.
Not true. If I look at my house mate's company and the companies he
works with (Alcatel, Lucent and others) it is clear that documentation
is used long beyond the initial design phase. As an example, my
housemate is working on finishing a project at the moment which has its
roots in a design Alcatel (Italian company) designed years ago. Because
the Alcatel engineers didn't bother to properly document the system back
then it resulted in a world of pain for both the Germans (Lucent) and my
house mate's company (AimCom). The Italians' constant refusal to
document system components in a proper manner let alone follow up on
deadlines has been really dragging down the project.
But still, those three plus a few other companies have been swapping
documentation and specs like there's no tomorrow. The spec for each part
takes hundreds of pages and details everything into excruciating detail.
I honestly can't think of how such a project would work without those
piles of pages filled with all of the information one'd need to
implement the project.
As for your argument that those books classify as 'documentation', I
disagree. They make for adequate reference works whenever the
information in them is current, but the point of a specification is to
have only the information one needs to implement a project together in
one document, not spread throughout a dozen or more reference books.
Those works also don't mention exact implementation details, TODOs or
other project-specific information. Generic info doesn't equal a
specification.
This aside from the point that you'd be spending a few hundred euro just
buying those books you reference, something every ROS dev would have to
do. We don't want to condone copyright infringement, do we?
Impractical, insufficient and cop-out are words that come to mind.
Sorry if I sound harsh, but this is among one of my many pet peeves ^_^
Maya