On Saturday 01 September 2007 09:13, Dossy Shiobara wrote: > Would there be interest in funding a tech. writer for a short period of > time? If we had a fund-raiser, perhaps we could hire one on a contract > basis for a couple of months? In that case, what goals would we like to > set? Those who would contribute funds: what documentation would you > like to see authored and/or updated?
Why don't we have an idea-raiser? Maybe it is a common disease among programmers: writing code is apparently the only thing which counts. Contributions to the community should be for things which are important, critical even. Why should we waste time doing unimportant tasks? There really are no degrees of importance: either it needs to be done, or it doesn't. Nice to have is way down the list. If documentation is so unimportant that it can be tasked to a contract tech writer and finished in a few months, why do it at all? I can't think of a single use for such a project. Current, very old, documentation is okay for beginners. Experienced users are probably not going to be helped by documentation written by someone unfamiliar with AOLserver. Documentation is more than a formalizm, it needs to have a purpose. Yes, not just code needs to be written for a purpose, but the documentation for the code needs a purpose. Nobody knows that purpose of the code, and the type of documentation that would best explain it, than those who write and use the code. Configuration settings, initialization and runtime information is also documentation. Writing code which provides initialization and runtime information can't be done by anyone else but the programmer. One thing left out so far is example code. Regardless of accepted practice of who writes or polishes up documentation in a given project, with no examples of use, how did the programmer/engineer test the API? Were there no design docs? No goal? If this isn't the exclusive task of a code writer, what in the hell is? Of course the programmer/engineer could claim that they just haven't written down their thoughts, but it is impossible to maintain that it isn't their job. My suggestion of revisiting how documentation is done doesn't apply to who should be doing it. It needs to be done by those writing, modifying and using the code. If someone doesn't think it is important to provide documentation, including discussion of goals, motivations, impact, etc. prior to doing coding, they don't deserve to be mucking around with the core API; do it in a module or in a private copy somewhere. We really need to grow up as a community and demand a quality, transparent process. The main reason for this is that the current code has not even been put into production by AOL. We should assume that this will remain the case. In addition, Jim Davidson has moved on, and like it or not, his guidance, although not visible, was known, or at least assumed and respected enough to accept the process as it was. Also, the team which was at least four inside AOL has been reduced to almost zero. This proves that we can't even rely on AOL to finish what they start. Nor should we, they are a commercial enterprise, and should be expected to operate for their own self-interest. In fact, we should expect anyone here to do so with respect to their business interests. BUT this self-interest does not extend into the core API. As community members, we need to act in the shared interest of the community. tom jackson -- AOLserver - http://www.aolserver.com/ To Remove yourself from this list, simply send an email to <[EMAIL PROTECTED]> with the body of "SIGNOFF AOLSERVER" in the email message. You can leave the Subject: field of your email blank.
