On Fri, 14 Dec 2001, Lamar Owen wrote: > On Friday 14 December 2001 04:45 am, Alexander Ehlert wrote: > > > audio current limitations log," right? :). You have said it the best: > > > Linux overall, is acutely suffering from lack of coherent documentation, > > > Every programmer should write the documentation himself as he understands > > what is going on, that is actually what we do in the GLAME project. > > You need a good technical writer to write good documentation. Typically, the > programmers are too close to the code to write good end-user docs. There, > are, of course, good programmers who are also good technical writers; but > they are the exception, not the rule.
Well, most important for developers is not end-user documentation, but API documentation - this part can be most easily done by the developer(s) who did implement the API rather than someone else trying to figure out whats going on by reading the source. Look f.i. at the current situation with the Alsa API and the Jack API (for the latter its probably too early to complain though). I for myself can say its very easy to at least write down the purpose of arguments passed to a API function and the possible return-values - adding one sentence on the purpose of the function itself isnt hard either. And the best is, it will help later to find out bugs wrt API consistency and/or bad implementation. The rule should be - first spec the API by writing a header _with_ documentation - then implement Richard. -- Richard Guenther <[EMAIL PROTECTED]> PGP: 2E829319 - 2F 83 FC 93 E9 E4 19 E2 93 7A 32 42 45 37 23 57 WWW: http://www.anatom.uni-tuebingen.de/~richi/
