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