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=== > >
