Subject: Re: [linux-audio-dev] Still I cannot understand why...
From: Richard Guenther (rguenth_AT_tat.physik.uni-tuebingen.de)
Date: Sun Dec 16 2001 - 15:35:21 EET
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 <richard.guenther_AT_student.uni-tuebingen.de> 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/
This archive was generated by hypermail 2b28 : Sun Dec 16 2001 - 15:31:13 EET