hopscc wrote:OK - so what makes you believe all those high quality doc pieces were generated using exactly and only the process you describe and that was the sole reason they are 'high quality' ( as opposed to 1 person or a small group generating them with or more likely without any external assistance or as 'closed' source).
Check those docs and to find out how they are generated and/or source code repos which may reveal how the doc is generated.
It does not matter whether it is group or 1 person (e.g. Nimrod is basically one-man-band), but the point is that most of the docs for the projects which I listed
do not keep their
main doc in wiki only.
I'd think a better indicator of quality output was a someone who knows what good targetted doc should look like, good architecture pointed at what you are trying to achieve, willingness to enforce/follow it, good book/tutorial writing skills and lots of user testing or input and iteration on the result, ...
I never wrote that for Cobra's docs there is problem with the
content, but with the structure
Of course it will - any additional overhead action is a barrier:
Just using a VCS - thats extra steps - both the idea of using, and getting the 'chosen' one, working out how to use it (over and above actually generating the content ) - complaining cos its not my favored one, and the syncing process itself...
That would filter out anyone who saw a mistake or thought of an addition/correction and just thought 'I can fix that'. Leading onto - hey this is easy write some more doc....
First of all, do some research and find out:
[*] how many people contributed significant amount of docs in last year?
[*] how many of those are not techy-savvy enough to contribute doc 'patches' using some (D)VCS ?
My opinion that any serious contributor to the project, should be familiar with the tools/VCS used by it.
I also complain that wiki is not my beloved tool, so what?
You can't satisfy everybody, but decide what is good for the project itself.
( I'm not sure I agree with either of your precondition assertions either)
No problem.
Its not that your process wouldnt work to gen something but its a different dynamic than allowing anyone who just wants to fix/do some doc to do so ( more toward a committed-to-completion, semi-closed, doc-development group,...)
If keeping wiki and having badly organized docs for the sake of occacional contributors being able to fix some typos online, then I consider it's a bad trade off.
I just expressed my opinion trying to offer constructive criticism in order to improve the image of the whol project 'cause atm I can't improve compiler itself, but I'm respecting your opinion in regard and understand that it is allowed to differ from mine.
Now, I won't beat that dead horse any longer considering that enough is said in regard.