Well maybe there are a few other people besides the super-reviewers qualified. "NeTDeMoN" <[EMAIL PROTECTED]> wrote in message 9f6q1g$gal$[EMAIL PROTECTED]">news:9f6q1g$gal$[EMAIL PROTECTED]... > As Gervase said, I am not talking about end-user documentation. I am talking > about the innards of the code. For instance, evey file in the source should > have something written about it. Every system - such as the event system > (both XP and non-XP) - should have documentation written about it. > > I am not saying that there are not writers who know how to write code also. > What I am saying is that the only people qualified (In my opinion) to write > developer documentation about the innards of Mozilla are the people who deal > with it on a regular basis. If a writer deals with Mozilla on a regular > basis and programs for Mozilla on a regular basis, then good - he can > probably do a very good job. I would also agree that many programmers are > not good writers. Most can write something halfway decent and many > programmers are excellent writers and choose not to do it. There is > something wrong with that. The programmers who deal with Mozilla on a > regular basis should be writing the preliminary documentation, and the > technical writers can then use those docs, learn Mozilla and writer their > own (possibly better) documentation. > > Obviously, what has been going on in the past - "Let the programmers program > and the writers write" - is not working. There needs to be some written > output from the developers before any ordinary technical writer can even > touch the project. It is not the job of the technical writer to stumble > around in the source code for six months without any guidance until they can > finally write about Mozilla. It is the job of the developers who are most > familiar with the code to do the writing. Then, and only then, will the code > be open for others to document it more clearly. > > There is a book coming out in August that should document Mozilla (hopefully > well), but what about all the wasted time until then? I have wasted so much > time making the same mistakes as everyone else when working with the code > when those mistakes should have been warned against. Developers for Mozilla > hit roadblocks that curtail their development for days. > > If a technical writer who has not been inside the Mozilla code can write a > document that explains how the code works and talks about all the pitfalls, > special situations, etc, then lets see it. I think that would be quite an > uphill battle. The only people who are qualified to document the source are > those that have a lot of experience with it - at least a year in my > opinion - and superreview the code they work on. > > > > > "Michael Tulloch" <[EMAIL PROTECTED]> wrote in message > [EMAIL PROTECTED]">news:[EMAIL PROTECTED]... > > On Tue, 29 May 2001, NeTDeMoN wrote: > > > > > I doubt a writer has the technical knowlege to document XPCOM, except in > a > > > > Then you have summarily disposed of the best person to do the job. The > > whole concept of quality is that you use those best fitted for the job > > to do the job. > > > > > rare occasion. Part of being an engineer is the ability to write > technical > > > documentation. That is why, when you take an engineering degree, you are > > > required to take writing courses. Mozilla 1.0 is not going to be the > end of > > > > The assumption that a few writing classes makes someone a writer is > > hilariously reductionist. Nor is writing well a principle attribute of > > many engineers (so writing is not subsumed in being an engineer). That > > much history speaks loud. > > > > > the project. It is going to go on after that. As for the current > process, in > > > my opinion - it sucks. There is not a documentation, and the > documentation > > > that is around is outdated and incomplete. If developers don't like > writing, > > > then in my opinion - tough! They should do it anyway. Either that, or > there > > > needs to be technical writers hired to learn how it all works and write > > > > But you'd best not use writers -- after all, people that know how to > > write can't possibly be as good at it as people who majored in > > Something Else. Also, lacking above is any concept of those who > > know both writing and programming (as I held out in my original > > email), or of the tech writer who can grasp technical concepts > > quickly. Instead, aspersion. > > > > > about it. But, I have more faith in the documentation being correct if a > > > developer writes it. The developers don't have to spit out a glossy > piece of > > > work, either. They just have to spit out something that someone else can > > > make glossy. > > > > The above attitude is precisely why technical documentation is > > usually of low quality. Such adherants refuse the overtures of those > > who major in clarity and then turn around and wonder (not unlike > > Hamlet) why the outcome is the way that it is. To patrionize those > > usually responsible for documentation is at best, unwise, and at > > worst, damanging not only to your own credibility, but to the > > credibility of Mozilla participants as a whole. > > > > You also missed my point about the whole nature of quality (early > > involvement). > > > > ~Mike > > =====CALLING ALL PATRIOTS==== > > Now is the time! Justice and liberty hang by a thread! > > Log on to freerepublic.com and make a difference! > > =====CALLING ALL PATRIOTS=== > > > > > >
